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-After` header 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 support@tesseraai.cloud 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.