1. 7API
  2. Docs
  3. Errors

Errors

Errors come back as JSON with an HTTP status code. The error.type and error.message fields are always present.

json
{ "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

StatusMeaningWhat to do
400The 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.
401The API key is missing or invalid.Check the header and key. See Authentication.
402insufficient_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.
403permission_denied: the key can't use this model. An upstream safety block can also return 403 permission_error.Use another model, or rephrase.
404Unknown endpoint, or a model that is retired or temporarily unavailable (model_unavailable).Check the path and the model list.
405 / 415Wrong HTTP method, or the body isn't JSON (Content-Type must be application/json).Use POST with a JSON body.
413The request body is larger than 25 MB.Send fewer or smaller images, or trim the history.
429A rate limit was hit (rate_limit_error), or the upstream is busy.Wait for the Retry-After header, then retry with backoff.
500Internal errorRetry with backoff.
502 / 503No 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.