Resources
Errors
OpenAI-shaped routes return the OpenAI error envelope. ElevenLabs-shaped routes return the ElevenLabs one. Stable codes, named parameters.
Last reviewed 2026-08-25
OpenAI envelope
{
"error": {
"message": "'model' is required.",
"type": "invalid_request_error",
"param": "model",
"code": "missing_required_parameter"
}
}Prop
Type
ElevenLabs envelope
ElevenLabs-shaped routes (/elevenlabs/v1/text-to-speech, /elevenlabs/v1/voices, /elevenlabs/v1/speech-to-text, /elevenlabs/v1/speech-to-speech, /elevenlabs/v1/history) return the ElevenLabs detail shape with 422 for validation errors, as the elevenlabs SDK expects.
{ "detail": { "status": "unsupported_parameter", "message": "diarize and num_speakers are not supported yet" } }Codes
| Status | code | Meaning | Recovery |
|---|---|---|---|
| 400 | unsupported_parameter | The field is not supported on this route. | Remove the field named in param. See Compatibility. |
| 400 | missing_required_parameter | A required field is absent. | Add the field named in param. |
| 400 | invalid_value | A value is outside the allowed set, for example response_format or endpoint. | Use a listed value. |
| 401 | invalid_api_key | Missing, wrong, or revoked key. | Check the header. |
| 402 | insufficient_balance | Account balance is zero. | Add credits. |
| 402 | key_spend_limit_reached | This key hit its period ceiling. | Raise the limit or use another key. |
| 404 | model_not_found | Unknown model id. | Use a model id from Pricing. |
| 404 | voice_not_found | Unknown voice id. Never a default voice. | Use a listed voice or alias. |
| 429 | rate_limit_exceeded | Per-key RPM or concurrency. | Wait Retry-After. |
| 502 | upstream_error | The model did not answer. Nothing billed. | Retry with backoff. |
| 503 | model_booting | The model is starting. | Wait Retry-After. |
| 503 | no_capacity | No capacity for the model right now. | Retry with backoff. |
Model errors
Errors raised by the model come back in the same envelope with the same status code. An out-of-range temperature arrives as a 400 with param set to temperature.
Handling errors in the SDK
import openai
try:
client.chat.completions.create(model="qwen3.8-27b", messages=msgs, audio={"voice": "alloy"})
except openai.BadRequestError as e:
print(e.body["code"], e.body["param"]) # unsupported_parameter audio
except openai.RateLimitError as e:
retry_after = int(e.response.headers.get("retry-after", "5"))
except openai.APIStatusError as e:
if e.status_code == 402:
print("add credits")