Errors and retries
Every error has one shape and a stable code. Decide by the code what to do, and retry only what can succeed.
The error body
Every error from a /v1 endpoint answers this body, the OpenAI-compatible ones included. It is OpenAI's error object with the request id added, so OpenAI SDKs read it as they always have.
| Field | Meaning |
|---|---|
error.type | The family of the error, set by the HTTP status. The types are listed below. |
error.code | A stable code for programs. Decide what to do by this field. |
error.message | What went wrong, written for people. It can change, so never match on it. |
error.param | The first invalid parameter, or null. |
error.fields | On validation errors only: each invalid field with its first message. |
request_id | This request's id, the same as the X-Request-Id header. |
A chat stream that fails after it has started sends one last event with this body, then [DONE]. The status is 200 by then, so read the event.
Error types
The type follows the status. These are the four types OpenAI uses.
| Status | Type |
|---|---|
402 | insufficient_quota |
429 | rate_limit_error |
5xx | server_error |
| Every other 4xx | invalid_request_error |
Request IDs
Every answer carries an X-Request-Id header, audio and errors included. Every error body and every data body repeats it as request_id; the OpenAI- and Cohere-compatible success bodies keep their own shape, so read the header there. Quote it when you contact support: it is how we find the request in our logs.
We make a new id for every request and ignore an X-Request-Id you send. A replayed answer gets a new id too.
When to retry
Decide by the status and the code. A retry that cannot succeed only uses up your rate limit.
| Answer | What to do |
|---|---|
429 | Wait the number of seconds in Retry-After, then send the same request again. |
500502503 | Back off and retry: wait 1 second, then 2, then 4, and stop after a few tries. Where the POST takes an Idempotency-Key (see below), repeat it with the same key, so it is never charged twice. |
409 job_not_finished | The job is still queued or running. Poll it again in a few seconds. |
409 idempotency_conflict | The key was already used with a different body. Send a new request with a new Idempotency-Key. |
409 job_failed410 audio_expired | The audio will not come. Create a new job. |
413 input_too_large422 input_too_large | Shorten the input or split it, then send it again. |
400401402403404405409 conflict422 | Never retry these unchanged. Fix the request, the key, its permissions, its limits or the balance first. |
Retrying a POST safely
Send an Idempotency-Key header of up to 191 characters on the POSTs below. A repeat with the same key gets the original result back with Idempotency-Replayed: 1, and nothing is done or charged again: the same audio or transcription, the job as it stands now, or the voice as it is now. A voice key whose voice was deleted since creates a new voice. Keys belong to your organization.
| Endpoint | Key kept for |
|---|---|
POST /api/v1/tts/synthesizePOST /api/v1/tts/dialogue | 7 days |
POST /api/v1/tts/jobs | Until the job is deleted, a day after it finishes by default |
POST /api/v1/stt/transcribePOST /api/v1/tts/voices | Always. Reuse a key only for the same request. |
The same key with a different body answers 409 idempotency_conflict, and a key over 191 characters answers 400 invalid_request.
Error codes
Every code the API can answer your requests with, and the status it comes with. New codes can appear, so handle a code you don't know by its status.
| Code | Meaning |
|---|---|
invalid_request400, 422invalid_request_error | The request is malformed or failed validation. |
invalid_api_key401invalid_request_error | The API key is missing or not recognized. |
api_key_disabled401invalid_request_error | The API key is disabled; it can be enabled again. |
api_key_revoked401invalid_request_error | The API key was revoked and can never be used again. |
api_key_expired401invalid_request_error | The API key is past its expiry date. |
insufficient_balance402insufficient_quota | The organization's balance is too low for this request. |
spend_limit_exceeded402insufficient_quota | The request would take the API key over its monthly spend limit. |
insufficient_permissions403invalid_request_error | The API key lacks the permission this request needs. |
ip_not_allowed403invalid_request_error | The request's IP address is not on the API key's allowlist. |
no_organization403invalid_request_error | The API key belongs to a user without an organization. |
voice_unavailable403invalid_request_error | The voice_id is not usable by this account. |
forbidden403invalid_request_error | This API key is not allowed to make this request. |
not_found404invalid_request_error | The route or resource does not exist in this organization. |
model_not_found404invalid_request_error | The requested model does not exist or is not available. |
method_not_allowed405invalid_request_error | The HTTP method is not supported on this route. |
conflict409invalid_request_error | The request conflicts with the current state of the resource. |
idempotency_conflict409invalid_request_error | The Idempotency-Key was already used with a different request. |
job_not_finished409invalid_request_error | The TTS job has not finished yet. |
job_failed409invalid_request_error | The TTS job failed and has no audio. |
gone410invalid_request_error | The resource is no longer available. |
audio_expired410invalid_request_error | The TTS job's audio is past its retention window. |
audio_too_large413invalid_request_error | The audio is too large to send as an MCP resource; download it from its link. |
input_too_large413, 422invalid_request_error | The input is over a size limit. |
unsupported_media_type415invalid_request_error | The uploaded media type is not supported. |
batch_too_large422invalid_request_error | The batch contains too many embedding inputs. |
too_many_documents422invalid_request_error | The request contains too many documents to rerank. |
context_length_exceeded422invalid_request_error | The prompt plus max_tokens exceeds the model's context length. |
upstream_rejected_input422invalid_request_error | The model server refused the input; retrying it unchanged will not succeed. |
rate_limit_exceeded429rate_limit_error | The API key's or its organization's per-minute request rate was exceeded. |
concurrency_limit_exceeded429rate_limit_error | Too many requests are in flight for this API key or its organization. |
upstream_rate_limited429rate_limit_error | The model server is at capacity; retry after a moment. |
too_many_active_jobs429rate_limit_error | Too many queued or running TTS jobs for this API key or its organization. |
server_error500server_error | An unexpected error occurred. |
synthesis_failed500server_error | Speech or dialogue generation failed; retry after a moment. |
transcription_failed500server_error | Transcription failed; retry after a moment. |
upstream_error502server_error | A model or voice service failed; retry after a moment. |
service_unavailable503server_error | A required service is temporarily unavailable. |
storage_failed503server_error | Audio was generated but could not be stored for an idempotent retry. |
A job that fails is not an error answer. It moves to failed and carries its own error.code, which the text to speech reference lists with the job.