Errors
Every error uses the OpenAI error shape, so SDK exception handling just works.
POSTerror shape
402{ "error": {
"message": "Out of credits. Top up at /dashboard/billing.",
"type": "insufficient_quota",
"code": "insufficient_credits"
} }
Top up, then send it again.retry: after a top-up
Shape
payload.jsonJSON
HTTP/1.1 402{ "error": { "message": "Out of credits. Top up at /dashboard/billing.", "type": "insufficient_quota", "code": "insufficient_credits" }}Branch on the HTTP status and code. The message is for humans and can change. code is null for generic 400s.
Codes
| Status | type | code | When | Do |
|---|---|---|---|---|
| 400 | invalid_request_error | (none) | Body not JSON, missing model, missing or empty messages, or the engine rejected a parameter. | Fix the request. Do not retry. |
| 401 | authentication_error | missing_key | No Authorization or x-api-key header. | Send a key. |
| 401 | authentication_error | invalid_key | Key unknown or revoked. | Create a new key. |
| 402 | insufficient_quota | insufficient_credits | Balance is zero or below. | Top up, then retry. |
| 402 | insufficient_quota | key_spend_limit | This key reached its spend limit. | Raise or reset the limit in the dashboard. |
| 403 | permission_error | model_not_allowed | Key is scoped and this model is not on its list. | Use an allowed model or edit the key. |
| 403 | permission_error | suspended | Account suspended. | Contact support. |
| 400 | invalid_request_error | context_length_exceeded | The prompt plus max_tokens is over the model's context window (the engine's message says by how much). | Trim the conversation or lower max_tokens. |
| 404 | invalid_request_error | model_not_found | Unknown model id. | GET /v1/models. |
| 404 | invalid_request_error | unknown_url | No such endpoint under /v1 (for example /v1/embeddings). | Use /v1/chat/completions or /v1/responses. |
| 400 | invalid_request_error | previous_response_not_found | Responses API: previous_response_id was sent, and UncensoredLLM stores no responses. | Send the whole conversation in input each call. |
| 404 | invalid_request_error | response_not_found | Responses API: GET, DELETE or cancel on /v1/responses/{id}. Nothing is stored to fetch. | Keep what the call returned. |
| 400 | invalid_request_error | unsupported_tool | Responses API: an OpenAI-hosted tool such as file_search or computer_use_preview. | Declare it as a function tool and run it yourself. |
| 429 | rate_limit_error | rate_limited | Over the per-minute request limit for your tier. The message reads like "Rate limit: 30 requests per minute (Tier 1)." | Back off and retry. |
| 429 | rate_limit_error | concurrency_limited | Too many requests in flight for your tier. API calls first wait up to 30 seconds for one of yours to finish. | Retry after the Retry-After delay, or send fewer at once. |
| 429 | rate_limit_error | chat_allowance_used | Chat app only: today's plan allowance is used up. It resets at 00:00 UTC. | Wait for the reset, or continue at API prices from your balance. |
| 502 | server_error | (none) | Search or scrape backend failed. | Retry after a moment. Not charged. |
| 503 | server_error | no_capacity | Every node stayed busy for the two minutes the call waited for one. | Retry after the Retry-After delay. |
| 503 | server_error | upstream_unavailable | Every node failed or errored, after a retry. | Retry after the Retry-After delay. |
| 504 | server_error | upstream_timeout | The model ran out of time before it finished (a very long reply or long thinking). Not charged when nothing came back. Sent with x-should-retry: false. | Ask for a shorter reply or less reasoning: the same call usually ends the same way. |
A 400, 413 or 422 from the model engine is passed through with the engine's message, type and code (for example context_length_exceeded). Typical cause: a parameter value the engine does not accept. Every response carries an x-request-id header; quote it when you report a problem.
Retry advice
- Retry: 429 (except
chat_allowance_used, which clears only at the 00:00 UTC reset), 502 and 503, plus network errors and timeouts. Use exponential backoff with jitter: 1s, 2s, 4s, capped around 30s, with a limit of a few attempts. - Do not retry: 400, 401, 402, 403, 404. The same request will fail the same way.
- 429 and 503 carry a
Retry-Afterheader in seconds, which the OpenAI SDKs honour; a 504 saysx-should-retry: false. Per-minute windows are 60 seconds, so after arate_limitedslow down as well. - A call that finds every node busy waits up to two minutes for one before it returns 503, so keep client timeouts above that (the OpenAI SDKs default to 10 minutes).
- The gateway already fails over between nodes inside a single request, so a 503 means every node tried was unavailable, not that it gave up early.
- Chat completions are not idempotent. A non-streaming call runs to the end once it has started, even if your client times out or hangs up, and its reply is billed; a retry can queue behind it and is billed too. For long generations, stream (hanging up stops a stream) and keep what you receive.
Related: rate limits, billing, authentication.