[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"article-doc:docs\u002Fapi-reference\u002F8.errors":3},"---\ntitle: Errors\ndescription: HTTP status codes, WebSocket error events, and error payload formats.\n---\n## Error response formats\n\n### OpenAI format (`\u002Fv1\u002Faudio\u002F*` endpoints)\n\nUsed for realtime WebSocket, offline HTTP, and session-token endpoints:\n\n```json\n{\n  \"error\": {\n    \"message\": \"API key is missing.\",\n    \"type\": \"invalid_request_error\",\n    \"code\": \"missing_api_key\"\n  }\n}\n```\n\n`type` is `rate_limit_error` for 429 responses, otherwise `invalid_request_error`.\n\n### Envelope format (Key management API)\n\n```json\n{\n  \"ok\": false,\n  \"error\": {\n    \"code\": \"admin_unauthorized\",\n    \"message\": \"Admin token required.\",\n    \"retryable\": false\n  }\n}\n```\n\n`retryable` is `true` for 429 and ≥500 responses.\n\n## HTTP error codes\n\n| Code | HTTP | Cause | Client action |\n|---|---|---|---|\n| `missing_api_key` | 401 | No Authorization header \u002F query token | Add API key |\n| `invalid_api_key` | 401 | Key format invalid or unknown | Check key |\n| `revoked_api_key` | 401 | Key has been revoked | Contact provider |\n| `expired_api_key` | 401 | Key has expired | Re-provision |\n| `auth_unavailable` | 503 | Key store unavailable | Retry later |\n| `invalid_session_token` | 401 | Session token invalid or expired | Obtain new token |\n| `token_issuer_unavailable` | 503 | Token issuer not configured | Retry later |\n| `websocket_required` | 426 | Non-WS upgrade request | Use WebSocket client |\n| `gateway_disabled` | 503 | Realtime gateway disabled | Contact provider |\n| `upstream_unavailable` | 503 | Upstream unavailable (circuit breaker) | Back off and retry |\n| `connection_rate_limited` | 429 | Connection rate exceeded | Honor `Retry-After` |\n| `concurrent_connection_limit` | 429 | Max concurrent connections exceeded | Wait for release |\n| `request_rate_limited` | 429 | Request rate exceeded | Honor `Retry-After` |\n| `audio_quota_exhausted` | 429 | Audio window budget exhausted | Retry later |\n| `audio_too_long` | 413 | Single request audio exceeds plan limit | Reduce audio duration |\n| `internal_error` | 500 | Uncaught exception | Contact provider |\n| `bad_request` | 400 | Invalid request body | Fix and retry |\n| `invalid_content_type` | 400 | Segment endpoint expects multipart; batch expects JSON on `\u002Fjobs` | Fix Content-Type and path |\n| `transcription_failed` | 502 | Segment transcription failed after worker attempts | Client may resend utterance |\n| `missing_file` | 400 | Segment request missing `file` field | Add multipart file |\n\n## WebSocket error events\n\nWithin an active WebSocket connection, the server may send `error` events:\n\n```json\n{ \"type\": \"error\", \"code\": \"...\", \"message\": \"...\", \"request_id\": \"...\" }\n```\n\n### WebSocket error codes\n\n| Code | Description | Close code |\n|---|---|---|\n| `audio_frame_too_large` | Audio frame exceeds 1 MiB | 1009 |\n| `concurrent_utterance_limit` | Concurrent utterance limit exceeded | — |\n| `upstream_backpressure` | Upstream backpressure | 1013 |\n| `client_backpressure` | Client backpressure | — |\n| `upstream_unavailable` | Upstream unavailable | 1013 |\n| `idle_timeout` | Idle timeout reached | 4408 |\n| `session_duration_limit` | Session duration exceeded | 1008 |\n| `session_audio_limit` | Session audio budget exceeded | 1008 |\n| `audio_quota_exhausted` | Audio quota exhausted | 1008 |\n| `bad_json` | JSON parse failure | — |\n| `bad_message` | Invalid message type | — |\n| `invalid_audio` | Invalid audio data | — |\n\n## Key management API errors\n\n| Code | HTTP | Description |\n|---|---|---|\n| `admin_unauthorized` | 401 | Missing admin token |\n| `invalid_plan` | 400 | Unknown plan |\n| `invalid_expiry` | 400 | Invalid or past expiry date |\n| `store_unavailable` | 500 | R2 storage unavailable |\n| `key_not_found` | 404 | Key ID not found |\n| `not_found` | 404 | Unknown management route |\n\n## Troubleshooting\n\n| Problem | Check |\n|---|---|\n| 401 `missing_api_key` | Ensure request includes `Authorization: Bearer sk-...` |\n| 401 `invalid_api_key` | Verify key starts with `sk-`, length ≥ 16 |\n| 429 `*_rate_limited` | Honor `Retry-After` header, exponential backoff |\n| 503 `upstream_unavailable` | Check `\u002Freadyz` for upstream status |\n| WS `idle_timeout` | Keep sending audio frames, or close explicitly |\n| WS `audio_frame_too_large` | Reduce frame size to ≤ 1 MiB |\n\n## Related\n\n- [Authentication](\u002Fdocs\u002Fstart\u002Fauthentication) — auth methods\n- [Reconnection & Retries](\u002Fdocs\u002Fproduction\u002Freconnection-retries) — retry strategies\n- [Rate Limits](\u002Fdocs\u002Fapi-reference\u002Frate-limits) — plan limits\n",1790059118945]