Skip to content
Docs/Platform/Errors

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

StatustypecodeWhenDo
400invalid_request_error(none)Body not JSON, missing model, missing or empty messages, or the engine rejected a parameter.Fix the request. Do not retry.
401authentication_errormissing_keyNo Authorization or x-api-key header.Send a key.
401authentication_errorinvalid_keyKey unknown or revoked.Create a new key.
402insufficient_quotainsufficient_creditsBalance is zero or below.Top up, then retry.
402insufficient_quotakey_spend_limitThis key reached its spend limit.Raise or reset the limit in the dashboard.
403permission_errormodel_not_allowedKey is scoped and this model is not on its list.Use an allowed model or edit the key.
403permission_errorsuspendedAccount suspended.Contact support.
400invalid_request_errorcontext_length_exceededThe 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.
404invalid_request_errormodel_not_foundUnknown model id.GET /v1/models.
404invalid_request_errorunknown_urlNo such endpoint under /v1 (for example /v1/embeddings).Use /v1/chat/completions or /v1/responses.
400invalid_request_errorprevious_response_not_foundResponses API: previous_response_id was sent, and UncensoredLLM stores no responses.Send the whole conversation in input each call.
404invalid_request_errorresponse_not_foundResponses API: GET, DELETE or cancel on /v1/responses/{id}. Nothing is stored to fetch.Keep what the call returned.
400invalid_request_errorunsupported_toolResponses API: an OpenAI-hosted tool such as file_search or computer_use_preview.Declare it as a function tool and run it yourself.
429rate_limit_errorrate_limitedOver the per-minute request limit for your tier. The message reads like "Rate limit: 30 requests per minute (Tier 1)."Back off and retry.
429rate_limit_errorconcurrency_limitedToo 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.
429rate_limit_errorchat_allowance_usedChat 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.
502server_error(none)Search or scrape backend failed.Retry after a moment. Not charged.
503server_errorno_capacityEvery node stayed busy for the two minutes the call waited for one.Retry after the Retry-After delay.
503server_errorupstream_unavailableEvery node failed or errored, after a retry.Retry after the Retry-After delay.
504server_errorupstream_timeoutThe 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-After header in seconds, which the OpenAI SDKs honour; a 504 says x-should-retry: false. Per-minute windows are 60 seconds, so after a rate_limited slow 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.