Errors

bad_requestHTTP 400, not retryable

The request failed validation or a message arrived out of order. The message says which field or rule.

unauthorizedHTTP 401, not retryable

The API key is missing, wrong or deleted, or its org is disabled.

insufficient_creditsHTTP 402, not retryable

Your org is out of credit, so the router refuses new connections and requests until you buy more. Connections already open carry on.

provider_key_missingHTTP 400, not retryable

Your org has no key stored for the provider. Add one under Provider keys.

provider_rejectedHTTP 400, not retryable

The provider refused the request, e.g. a wrong stored provider key or an unknown voice. The provider’s message is passed through.

provider_rate_limitedHTTP 429, retryable

Your own quota at the provider is exhausted.

provider_unavailableHTTP 502, retryable

The provider returned a server error, or the connection to it failed or closed unexpectedly.

provider_timeoutHTTP 504, retryable

The provider took too long to send audio.

internalHTTP 500, retryable

The router failed.

The HTTP status is what /v1/audio/speech answers with. provider_status, when present, is the status the provider answered with.

WebSocket (/v1/stream). An error message ends the segment; close the connection and open a new one. segment_id is null for an error before a valid start. Two refusals come before the connection opens, as the HTTP status of the handshake: 403 for an API key the router doesn’t accept, and 402 (insufficient_credits) when your org is out of credit.

{"type": "error", "segment_id": "c0ffee", "code": "provider_rejected", "message": "…", "retryable": false, "provider_status": 403}

/v1/audio/speech. A JSON body with the status above. The status is sent with the first audio, so an error after audio has started can only abort the body: treat a response that ends early as failed.

HTTP/1.1 400 Bad Request{"error": {"code": "provider_key_missing", "message": "…", "retryable": false, "provider_status": null}}

Provider drop-ins. In the provider’s own format and status, as the provider sent them, so your client’s error handling keeps working. The one error of the router’s own, insufficient_credits, comes as HTTP 402 in the provider’s error shape (on ElevenLabs’ WebSockets, as an in-band error and close 1008). See Sarvam, Raya and ElevenLabs.

HTTP/1.1 401 Unauthorized{"error": {"code": "unauthenticated", "message": "invalid API key"}}

The dashboard’s API adds these, from managing an org’s members. Each /api/orgs/… route also checks your role in the org: forbidden (403) when it isn’t enough, not_found (404) when you aren’t a member.