Appearance
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"
}
}| Field | Description |
|---|---|
type | The category of error. Use it to decide whether to retry |
code | The exact error. Branch on this |
message | A description for people reading logs. It can change, so do not parse it |
request_id | The same value as the X-Request-Id header. Log it, and include it when you contact support |
param | The 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"))
raisejs
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
| Status | type | Meaning |
|---|---|---|
| 400 | invalid_request | The request is invalid. Sending it again unchanged will fail again |
| 401 | authentication_error | The API key is missing, unknown, revoked or expired |
| 402 | billing_error | Out of credit, or over the monthly spending limit |
| 403 | permission_error | The key is not allowed to do this |
| 404 | not_found | No such model, voice or resource |
| 409 | conflict | The request conflicts with the current state |
| 422 | invalid_request | The body failed validation. param names the field |
| 429 | rate_limit_error | Too many requests, or too many at once. Wait for retry-after |
| 500 | api_error | Something failed on our side. Retry once, then contact support with the request id |
| 503 | api_error | Temporarily unavailable or at capacity. Wait for retry-after |
Error codes
Authentication
| Code | Status | Meaning |
|---|---|---|
missing_api_key | 401 | No Authorization header arrived |
invalid_api_key | 401 | The key does not exist |
api_key_revoked | 401 | The key was revoked |
api_key_expired | 401 | The key is past its expiry date |
organization_suspended | 403 | API access for the organization is suspended. Contact support |
See Authentication.
Billing
| Code | Status | Meaning |
|---|---|---|
insufficient_credits | 402 | The balance is empty. Top up in the dashboard |
spending_limit_reached | 402 | The organization reached its monthly spending limit. Raise it in the dashboard |
Both are fixed in the dashboard, not in code. See Billing.
Rate limits
| Code | Status | Meaning |
|---|---|---|
rate_limit_exceeded | 429 | Over a per-minute limit |
concurrency_limit_exceeded | 429 | Too many requests in progress at once |
Both include retry-after. See Rate limits.
Models and voices
| Code | Status | Meaning |
|---|---|---|
invalid_model | 400 | No such model, or not a model this endpoint can use |
model_unavailable | 404 | The model cannot serve requests right now. Retry later |
invalid_voice | 404 | No such voice |
voice_not_supported | 400 | The voice is not available on this model |
unsupported_language | 400 | The model, or for speech the voice, does not support this language |
unsupported_response_format | 400 | The model does not offer this format, or cannot stream it |
unsupported_speed | 400 | speed is outside the model's range |
realtime_not_supported | 400 | The 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
| Code | Status | Meaning |
|---|---|---|
file_too_large | 400 | The upload is over 25 MB |
audio_too_long | 400 | The audio is longer than 10 minutes |
invalid_audio | 400 | The file is unreadable, in an unsupported format, or has no audio |
unsupported_audio_format | 400 | The audio cannot be transcribed in this encoding. Send 16-bit PCM WAV |
invalid_input | 400 | The model could not process this input |
input_too_long | 400 | The input is longer than the model can handle in one request |
Availability
| Code | Status | Meaning |
|---|---|---|
model_overloaded | 503 | The model is at capacity. Retry after retry-after |
service_unavailable | 503 | A temporary problem on our side. Retry after retry-after |
model_error | 500 | The 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/speechwithoutstream_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=trueon transcriptions,stream_format="sse"on speech): anerrorevent with the usual body. The OpenAI SDKs raise it from the loop, so the failure is never silent. - Realtime: an
errorevent, 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
| Status | Retry? |
|---|---|
| 429 | Yes, after retry-after, with jitter |
| 503 | Yes, after retry-after, with backoff and a maximum number of attempts |
| 500 | Once, with backoff. If it fails again, contact support with the request id |
| 400, 401, 403, 404, 409, 422 | No. Fix the request or the account first |
| 402 | No. 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.