API Reference

Error shape

The same logical fields appear in JSON HTTP responses and WebSocket error events.

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_audio_format",
    "message": "public audio must be PCM16LE at 24000 Hz mono",
    "request_id": "req_EXAMPLE"
  }
}

Retry with intent

Retry transient catalog, store, or upstream failures with bounded backoff. Do not retry invalid audio or authentication failures blindly.

Safe diagnostics

Error payloads never include bearer keys, provider URLs, raw upstream payloads, private room data, or unbounded audio/transcripts.

Error codes

Use the HTTP status and code together when deciding whether to retry or ask the user to change input.

Code	HTTP	Meaning
`invalid_vr_sk`	`401`	The secret key is missing, invalid, revoked, or outside the resource owner boundary.
`model_not_found`	`404`	The requested catalog model does not exist or is not available to this key.
`model_not_allowed`	`403`	The key is not allowed to use the selected model.
`insufficient_wallet_balance`	`402`	The prepaid wallet cannot cover the session preauthorization.
`idempotency_conflict`	`409`	An idempotency key was reused with a different owner or request body.
`session_not_found`	`404`	The session does not exist for the authenticated owner.
`session_expired`	`410`	The session passed its attach or lifecycle expiry window.
`unsupported_parameter`	`400`	A request or event contains a field outside the public contract.
`unsupported_audio_format`	`400`	Audio is not raw PCM16LE, 24 kHz, mono audio.
`invalid_audio`	`400`	Audio is empty, malformed, odd-sized, oversized, or invalid base64.
`rate_limited`	`429`	The caller exceeded the applicable request or session rate limit.
`provider_unavailable`	`502`	The selected upstream route could not produce a response.
`session_terminated`	`409`	The session is terminal and cannot accept more events.

Transport behavior

Authentication and ownership failures happen before the realtime upgrade.

401 invalid_vr_sk is returned before a WebSocket is accepted, so no new reservation is created.
invalid_audio covers empty, malformed, odd-sized, oversized, or invalid base64 audio.
unsupported_parameter is returned for event fields outside the public session contract.
session_terminated means the client must create a new session before sending more audio.