Error codes

Every error code and what to do about it.

Every error has a stable code you can rely on. For step-by-step fixes see Troubleshooting.

Status	Code	What it means	What to do
400	`invalid_request`	The request body is broken or has an unsupported value.	Fix the request.
400	`context_length_exceeded`	The conversation is longer than the model's context window.	Shorten it, or use a model with a bigger context.
401	`invalid_api_key`	Key missing, wrong, revoked or expired.	Send a valid key.
402	`insufficient_balance`	Not enough balance or free tokens to pay for the request.	Top up, claim free tokens, or buy a plan.
402	`model_allowance_exhausted`	Your plan allowance for this model is used up and the key has no balance fallback.	Wait until `reset_at`, use another model, or turn on fallback.
402	`upstream_spend_limit_reached`	This model has hit a temporary spending cap.	Try later or use another model.
403	`model_not_in_plan`	Your plan does not include this model.	Use a model from your plan, or turn on balance fallback.
404	`not_found`	Unknown model id or wrong URL.	Check the model id and the base URL.
429	`rate_limited`	Too many requests from your key or account.	Wait for `Retry-After` seconds.
429	`upstream_rate_limited`	The model is busy right now.	Wait for `Retry-After` seconds, or use another model.
502	`upstream_error`	The model could not answer after retries.	Retry; contact support if it continues.
503	`auth_unavailable`	Your key could not be checked for a moment.	Retry after a few seconds.
503	`no_supply` with `Retry-After`	No provider is serving this model right now — a temporary supply gap, not a broken model.	Retry after `Retry-After` seconds, or use another model.
503	`no_supply` without `Retry-After`	No seller meets the discount floor configured for this model — a configuration problem on our side, so retrying will not help.	Do not retry. Contact support with the `x-air-request-id` of the failed request.

Error format

OpenAI-format endpoints:

{
  "error": {
    "message": "model not available on your plan: deepseek-v4-pro",
    "type": "invalid_request_error",
    "code": "model_not_in_plan"
  }
}

The Anthropic-format endpoint (/v1/messages) wraps the same fields as { "type": "error", "error": { ... } }.

Useful response headers

x-air-request-id — the id of the request. Include it when you contact support.
x-air-model — the model id of your request.
Retry-After — seconds to wait before retrying (on 429 and some 5xx). A 503 no_supply without this header is not transient: it is a configuration problem on our side, so retrying only wastes requests.
x-air-reset-at — when an exhausted allowance resets (on 402).