Error format
All API errors follow the OpenAI envelope: a JSON body with an error field containing message, type, and optionally code and param.
Example error
{
"error": {
"message": "Incorrect API key provided. You can find your API key in your welcome email.",
"type": "invalid_request_error",
"code": "invalid_api_key",
"param": null
}
}HTTP codes
| Code | Meaning | Retry? |
|---|---|---|
| 400 | Malformed request: invalid JSON, missing required field, parameter out of range | No — fix the client |
| 401 | API key missing or invalid | No — verify the key |
| 403 | Valid API key without permission for this resource or model | No — contact support |
| 404 | Model or endpoint does not exist | No — fix model or URL |
| 413 | Payload too large (audio >25 MB, oversized context) | No — split the input |
| 422 | Semantic validation failed (unsupported audio format, invalid dimensions) | No — fix the client |
| 429 | Rate limit exceeded | Yes, with backoff — see /docs/api/rate-limits |
| 500 | Internal server error | Yes, with exponential backoff |
| 502 / 503 | Backend temporarily unavailable (maintenance, cold GPU) | Yes, with backoff |
| 504 | Upstream timeout (request took too long) | Yes; consider reducing context |
Error types in `error.type`
| Type | When it appears |
|---|---|
invalid_request_error | Malformed body, incompatible parameters, unsupported format |
authentication_error | Missing or invalid key (also 401) |
permission_error | Key without access to the model or endpoint (403) |
rate_limit_error | Quota exhausted in current window (429) |
api_error | Internal error; typically transient (500) |
overloaded_error | Backend saturated; retry with backoff (503) |
Retry strategy
- Only retry on 429, 500, 502, 503 and 504. Everything else is a client error and will not resolve via retries.
- Exponential backoff with random jitter:
min(60, 2^attempt + random())seconds. Detail at /docs/api/rate-limits. - Honour the
Retry-Afterheader when present — the API tells you how long to wait. - After 5 consecutive failed retries, escalate to an alert or failure log instead of retrying indefinitely.
When to contact support
For recurring errors that retries do not resolve, email [email protected] and include: UTC timestamp, request id if present in headers, error code and body, and the endpoint called. Response time: <4h business on Pro, <1h business on Scale, shared Slack on Enterprise.