Errors
Errors come back as JSON with an HTTP status code. The error.type and error.message fields are always present.
{ "error": { "type": "insufficient_balance", "message": "Out of balance. Top up via the Telegram bot." } }When the failure happened at an upstream provider, the body follows the format of the endpoint you called. Chat Completions and Responses get {"error": {"message", "type", "code", "param"}}. Messages gets {"type": "error", "error": {"type", "message"}}. The message may end with Reference code: …. Include that code if you contact support.
Status codes
| Status | Meaning | What to do |
|---|---|---|
| 400 | The request is invalid: malformed JSON, a missing or overlong model (max 128 characters), an out-of-range max_tokens, conflicting output-limit fields, an unsupported effort value, a model not available on this format, or a prompt longer than the model's context window (context_length_exceeded). | Fix the request. Don't retry it unchanged. |
| 401 | The API key is missing or invalid. | Check the header and key. See Authentication. |
| 402 | insufficient_balance. Either the balance is zero, or this request's worst-case cost (input plus the full max_tokens) is more than the remaining balance. | Top up, or lower max_tokens. |
| 403 | permission_denied: the key can't use this model. An upstream safety block can also return 403 permission_error. | Use another model, or rephrase. |
| 404 | Unknown endpoint, or a model that is retired or temporarily unavailable (model_unavailable). | Check the path and the model list. |
| 405 / 415 | Wrong HTTP method, or the body isn't JSON (Content-Type must be application/json). | Use POST with a JSON body. |
| 413 | The request body is larger than 25 MB. | Send fewer or smaller images, or trim the history. |
| 429 | A rate limit was hit (rate_limit_error), or the upstream is busy. | Wait for the Retry-After header, then retry with backoff. |
| 500 | Internal error | Retry with backoff. |
| 502 / 503 | No upstream could serve the request right now (overloaded_error on Anthropic format), or the gateway is briefly busy. | Retry with backoff. Check status if it persists. |
Retry policy
Retry 429, 500, 502, 503 and 504 with exponential backoff and jitter, honoring Retry-After when it's present. Don't retry other 4xx errors unchanged.
The gateway already fails over between upstream providers before it returns an error. A 5xx means that failover was also exhausted, so waiting a little before retrying helps more than retrying immediately.
Billing on errors
A request that fails without delivering any output isn't charged. If a stream fails partway, you pay only for the tokens that were delivered.
