Errors & troubleshooting
Understand API errors, status codes, and WebSocket failures.
Error responses
Errors use the envelope of the surface you called. Native endpoints return { "error": "<code>" }, ElevenLabs-compatible /el endpoints return a detail object, and OpenAI-compatible /oai endpoints return an OpenAI error object. This includes authentication errors: a failed /el or /oai request returns that SDK's envelope, not the flat native one, so the official client can deserialize it.
Native endpoint errors
{ "error": "invalid_api_key" }Common status codes
| Status | Error | Retry? | Meaning |
|---|---|---|---|
401 | missing_api_key | invalid_api_key | No | Send Authorization: Bearer with an active AllModels key. |
402 | insufficient_balance | No | The request cannot start until balance is available. |
403 | tenant_disabled | provider_not_allowed | No | The key or selected provider is not allowed. |
413 | tts_text_too_large | No | Split large TTS inputs into smaller requests. |
422 | validation | indeterminate_audio_duration | model_not_priced | No | Fix required fields, use a supported audio container, or choose a priced model. |
426 | upgrade_required | No | Open the endpoint as a WebSocket connection. |
501 | not_implemented | No | The /el or /oai path is part of that SDK but is not implemented by AllModels. The response carries x-should-retry: false. |
502 | upstream_error | No | The selected provider failed or returned an unusable response. |
Authentication and balance checks (401, 402, 403) run before the not-implemented check, so a keyless or zero-balance call to an unimplemented /el or /oai path fails with the auth status rather than 501. See OpenAI compatibility and ElevenLabs compatibility for what each surface implements.
WebSocket close codes
WebSocket auth failures close with 4401 for invalid keys and 4403 for disabled tenants or disallowed providers. The close reason carries a JSON { "error": "<code>" } payload.
Debugging checklist
- Call the public
GET /v1/modelsendpoint and confirm that the model supports your provider. - Use the full
{author}/{modelName}model name before trying an alias. - Check that the model supports your request type: streaming or synchronous.
- For WebSockets, send the API key when opening the connection and make sure your client requests a WebSocket upgrade.