Error codes
The canonical error table.
The gateway returns a stable code in every error body so clients can branch deterministically.
| Status | Code | Meaning | Client action |
|---|---|---|---|
| 400 | invalid_request | Malformed JSON body or unsupported parameters. | Fix the body and retry. |
| 401 | invalid_api_key | Missing or invalid API key. | Send a valid key. |
| 402 | model_allowance_exhausted | Plan allowance for this model is exhausted and balance fallback is off. Carries reset_at. | Wait until reset_at, switch model, or enable fallback. |
| 402 | insufficient_balance | Prepaid balance too low. Carries reset_at. | Top up or wait. |
| 402 | upstream_spend_limit_reached | Upstream spend cap reached. Carries reset_at when available. | Wait or switch model. |
| 403 | model_not_in_plan | The model is not enabled on your plan. | Use an allowed model. |
| 404 | not_found | Unknown model or endpoint. | Check the model name. |
| 429 | rate_limited | Per-key request rate limit exceeded. | Retry after Retry-After. |
| 429 | upstream_rate_limited | All upstream keys are rate-limited or cooling down. | Retry after Retry-After. |
| 502 | upstream_error | All upstream attempts failed. | Retry; contact support if it persists. |
The response also carries x-air-request-id for support. x-air-model echoes the canonical model you requested.