Skip to content

Errors ​

Every error, on every endpoint, has the same body:

json
{
  "error": {
    "type": "invalid_request",
    "code": "audio_too_long",
    "message": "Audio must be at most 600 seconds long.",
    "request_id": "req_01J8XQ2K7Z4N9P0R1S2T3V4W5X"
  }
}
FieldDescription
typeThe category of error. Use it to decide whether to retry
codeThe exact error. Branch on this
messageA description for people reading logs. It can change, so do not parse it
request_idThe same value as the X-Request-Id header. Log it, and include it when you contact support
paramThe field at fault, when there is one

Handling errors in the SDKs ​

The OpenAI SDKs raise their usual exceptions, such as BadRequestError, AuthenticationError and RateLimitError, with the error body attached:

python
import openai

try:
    speech = client.audio.speech.create(model="cadence-tts", voice="clara", input=text)
except openai.APIStatusError as exc:
    error = (exc.body or {}).get("error", {})
    log.error("xvoice %s: %s (request_id=%s)",
              error.get("code"), error.get("message"), error.get("request_id"))
    raise
js
import OpenAI from 'openai'

try {
  await client.audio.speech.create({ model: 'cadence-tts', voice: 'clara', input: text })
} catch (err) {
  if (err instanceof OpenAI.APIError) {
    console.error(`xvoice ${err.code}: ${err.message} (request_id=${err.requestID})`)
  }
  throw err
}

Validation errors ​

A body that fails validation returns 422 with code validation_error. param names the first field at fault, and details lists every problem found:

json
{
  "error": {
    "type": "invalid_request",
    "code": "validation_error",
    "message": "voice: Field required (1 more in details)",
    "param": "voice",
    "request_id": "req_01J8XQ2K7Z4N9P0R1S2T3V4W5X",
    "details": [
      {"param": "voice", "message": "Field required"},
      {"param": "speed", "message": "Input should be less than or equal to 4"}
    ]
  }
}

Nested fields are written with dots, such as metadata.name. param is absent when the problem is the body as a whole, such as malformed JSON.

Status codes ​

StatustypeMeaning
400invalid_requestThe request is invalid. Sending it again unchanged will fail again
401authentication_errorThe API key is missing, unknown, revoked or expired
402billing_errorOut of credit, or over the monthly spending limit
403permission_errorThe key is not allowed to do this
404not_foundNo such model, voice or resource
409conflictThe request conflicts with the current state
422invalid_requestThe body failed validation. param names the field
429rate_limit_errorToo many requests, or too many at once. Wait for retry-after
500api_errorSomething failed on our side. Retry once, then contact support with the request id
503api_errorTemporarily unavailable or at capacity. Wait for retry-after

Error codes ​

Authentication ​

CodeStatusMeaning
missing_api_key401No Authorization header arrived
invalid_api_key401The key does not exist
api_key_revoked401The key was revoked
api_key_expired401The key is past its expiry date
organization_suspended403API access for the organization is suspended. Contact support

See Authentication.

Billing ​

CodeStatusMeaning
insufficient_credits402The balance is empty. Top up in the dashboard
spending_limit_reached402The organization reached its monthly spending limit. Raise it in the dashboard

Both are fixed in the dashboard, not in code. See Billing.

Rate limits ​

CodeStatusMeaning
rate_limit_exceeded429Over a per-minute limit
concurrency_limit_exceeded429Too many requests in progress at once

Both include retry-after. See Rate limits.

Models and voices ​

CodeStatusMeaning
invalid_model400No such model, or not a model this endpoint can use
model_unavailable404The model cannot serve requests right now. Retry later
invalid_voice404No such voice
voice_not_supported400The voice is not available on this model
unsupported_language400The model, or for speech the voice, does not support this language
unsupported_response_format400The model does not offer this format, or cannot stream it
unsupported_speed400speed is outside the model's range
realtime_not_supported400The model does not support realtime sessions

The unsupported_* errors name the model and list what it does accept. The same information is in the model's speech_options on GET /v1/models.

Input ​

CodeStatusMeaning
file_too_large400The upload is over 25 MB
audio_too_long400The audio is longer than 10 minutes
invalid_audio400The file is unreadable, in an unsupported format, or has no audio
unsupported_audio_format400The audio cannot be transcribed in this encoding. Send 16-bit PCM WAV
invalid_input400The model could not process this input
input_too_long400The input is longer than the model can handle in one request

Availability ​

CodeStatusMeaning
model_overloaded503The model is at capacity. Retry after retry-after
service_unavailable503A temporary problem on our side. Retry after retry-after
model_error500The model failed on this request. Retry once
stream_interrupted—A stream or realtime session ended early. Sent in band

Realtime sessions have their own codes as well. See Realtime transcription.

Errors after a 200 ​

Once a streaming response has started, its status code cannot change. A failure partway through is reported inside the stream instead:

  • Streamed audio (POST /v1/audio/speech without stream_format="sse"): the connection closes before the body is complete. Most HTTP clients raise an error for this. Check for it rather than saving whatever arrived.
  • Server-sent events (stream=true on transcriptions, stream_format="sse" on speech): an error event with the usual body. The OpenAI SDKs raise it from the loop, so the failure is never silent.
  • Realtime: an error event, then the socket closes. The close code alone does not give the reason, so read the event. See Realtime transcription.

A stream that ends with no error event means the connection dropped.

Retries ​

StatusRetry?
429Yes, after retry-after, with jitter
503Yes, after retry-after, with backoff and a maximum number of attempts
500Once, with backoff. If it fails again, contact support with the request id
400, 401, 403, 404, 409, 422No. Fix the request or the account first
402No. Add credit or raise the spending limit first

The OpenAI SDKs already retry 429 and 5xx responses with backoff, twice by default. Set max_retries (Python) or maxRetries (Node.js) to change that, or to 0 to handle retries yourself.

A request that fails after work has started may already be billed, so retrying it can cost twice. See What is billed.

xVoice is a product of Stochastic Inc.