Documentation · Errors & limits

API

Errors & limits

Status codes, the error format and how to retry correctly.

Error format#

Errors follow the OpenAI format — an HTTP status plus an error object:

401 Unauthorized
{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Status codes#

CodeMeaningWhat to do
400Bad requestCheck the request body and parameters.
401Missing or invalid keyCheck the Authorization header and the key itself.
402Insufficient balanceTop up — or wait for the requests already running: they hold a reserve on the balance.
403Key restrictedThe key hit its spending limit, was revoked, or the model or IP address is not allowed by the key's settings (model_not_allowed, ip_not_allowed).
404Model not foundCheck the model id against the catalog.
429Too many requestsRetry later with exponential backoff. concurrency_limit — too many requests are running at once: wait for one of them to finish.
500Internal errorRetry; if it persists, contact support.
502, 503Provider unavailableRetry later or pick another model.
504Timed outLower max_tokens or switch to streaming.

Retries#

Retry only 429 and 5xx errors, with a growing pause: 1, 2, 4, 8 seconds. If the response has a Retry-After header, wait as long as it says. Other 4xx errors will not succeed on retry — the request needs fixing.

The official OpenAI and Anthropic SDKs already retry these for you (twice by default); tune it with max_retries.

Timeouts#

Large models and long answers take time — sometimes minutes. Give your client a timeout of at least 120 seconds, or use streaming: the first tokens arrive sooner and the connection never sits idle.

Limits#

Requests per minute per key and requests running at once per account depend on the plan. When you exceed them the API answers 429 — pause and retry. Each key's spending limit, allowed models and IP addresses are yours to set in the dashboard.

More in Reliability & limits, including how flua moves a request to a fallback model when a provider does not answer.