Error Handling

The JavaScript SDK provides typed error classes and an onError callback to handle failures gracefully.

The onError Callback

Pass onError when creating a stream to catch errors during the stream lifecycle:

const vision = new RealtimeVision({
  apiKey: 'your-api-key',
  model: 'Qwen/Qwen3.5-9B',
  prompt: 'Read any visible text',
  source: { type: 'camera', cameraFacing: 'environment' },
  onResult: (result) => {
    console.log(result.result)
  },
  onError: (error) => {
    console.error('Stream error:', error.message)
 
    if (error.name === 'UnauthorizedError') {
      // Invalid or revoked API key
    } else if (error.name === 'InsufficientCreditsError') {
      // Out of credits -- top up at platform.overshoot.ai
    } else if (error.name === 'NetworkError') {
      // Connection lost
    }
  }
})

If you don't provide onError, errors are logged to the console.

Error Classes

All errors extend ApiError, which extends the standard Error:

class ApiError extends Error {
  statusCode?: number
  requestId?: string
  details?: any
}

Additional HTTP Status Codes

These are returned by the API and surfaced through the error classes:

Fatal vs Non-Fatal Errors

Fatal errors stop the stream. After a fatal error, you need to create a new stream:

• Keepalive failure (stream lease expired)
• WebSocket connection error
• Transport connection loss
• Server-initiated closure
• Insufficient credits (402 during keepalive)

Non-fatal errors are reported through onError but the stream keeps running:

• WebSocket message parse errors
• Individual inference failures (reported in result.ok / result.error)

For conceptual details on error categories, see Error Handling.

Checking Results for Errors

Individual inference calls can fail without stopping the stream. Always check result.ok:

onResult: (result) => {
  if (!result.ok) {
    console.warn('Inference failed:', result.error)
    return
  }
  console.log(result.result)
}

See Output for the full result object.