Error Handling

For SDK-specific error classes and usage patterns, see JavaScript SDK or Python SDK.

Both SDKs provide typed error classes and error callbacks to help you handle failures gracefully.

Error Callbacks

Pass an error callback when creating a stream to catch errors during the stream lifecycle:

const vision = new RealtimeVision({
  apiKey: 'your-api-key', // Get yours at platform.overshoot.ai/api-keys
  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 === 'NetworkError') {
      // Connection lost
    }
  }
})

Error Classes

All errors extend ApiError, which extends the standard Error:

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

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)

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.