Skip to content

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.

JSON
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "The text field is required.",
    "param": "text",
    "fields": {
      "text": "The text field is required."
    }
  },
  "request_id": "0b8e8a5e-6f5c-4f7e-9d63-2c1f0f4b7a51"
}

FieldMeaning
error.typeThe family of the error, set by the HTTP status. The types are listed below.
error.codeA stable code for programs. Decide what to do by this field.
error.messageWhat went wrong, written for people. It can change, so never match on it.
error.paramThe first invalid parameter, or null.
error.fieldsOn validation errors only: each invalid field with its first message.
request_idThis 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.

StatusType
402insufficient_quota
429rate_limit_error
5xxserver_error
Every other 4xxinvalid_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.

AnswerWhat 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.

EndpointKey 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.

CodeMeaning
invalid_request

400, 422invalid_request_error

The request is malformed or failed validation.
invalid_api_key

401invalid_request_error

The API key is missing or not recognized.
api_key_disabled

401invalid_request_error

The API key is disabled; it can be enabled again.
api_key_revoked

401invalid_request_error

The API key was revoked and can never be used again.
api_key_expired

401invalid_request_error

The API key is past its expiry date.
insufficient_balance

402insufficient_quota

The organization's balance is too low for this request.
spend_limit_exceeded

402insufficient_quota

The request would take the API key over its monthly spend limit.
insufficient_permissions

403invalid_request_error

The API key lacks the permission this request needs.
ip_not_allowed

403invalid_request_error

The request's IP address is not on the API key's allowlist.
no_organization

403invalid_request_error

The API key belongs to a user without an organization.
voice_unavailable

403invalid_request_error

The voice_id is not usable by this account.
forbidden

403invalid_request_error

This API key is not allowed to make this request.
not_found

404invalid_request_error

The route or resource does not exist in this organization.
model_not_found

404invalid_request_error

The requested model does not exist or is not available.
method_not_allowed

405invalid_request_error

The HTTP method is not supported on this route.
conflict

409invalid_request_error

The request conflicts with the current state of the resource.
idempotency_conflict

409invalid_request_error

The Idempotency-Key was already used with a different request.
job_not_finished

409invalid_request_error

The TTS job has not finished yet.
job_failed

409invalid_request_error

The TTS job failed and has no audio.
gone

410invalid_request_error

The resource is no longer available.
audio_expired

410invalid_request_error

The TTS job's audio is past its retention window.
audio_too_large

413invalid_request_error

The audio is too large to send as an MCP resource; download it from its link.
input_too_large

413, 422invalid_request_error

The input is over a size limit.
unsupported_media_type

415invalid_request_error

The uploaded media type is not supported.
batch_too_large

422invalid_request_error

The batch contains too many embedding inputs.
too_many_documents

422invalid_request_error

The request contains too many documents to rerank.
context_length_exceeded

422invalid_request_error

The prompt plus max_tokens exceeds the model's context length.
upstream_rejected_input

422invalid_request_error

The model server refused the input; retrying it unchanged will not succeed.
rate_limit_exceeded

429rate_limit_error

The API key's or its organization's per-minute request rate was exceeded.
concurrency_limit_exceeded

429rate_limit_error

Too many requests are in flight for this API key or its organization.
upstream_rate_limited

429rate_limit_error

The model server is at capacity; retry after a moment.
too_many_active_jobs

429rate_limit_error

Too many queued or running TTS jobs for this API key or its organization.
server_error

500server_error

An unexpected error occurred.
synthesis_failed

500server_error

Speech or dialogue generation failed; retry after a moment.
transcription_failed

500server_error

Transcription failed; retry after a moment.
upstream_error

502server_error

A model or voice service failed; retry after a moment.
service_unavailable

503server_error

A required service is temporarily unavailable.
storage_failed

503server_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.