# Errors

> Every error code the Tokens API returns, what it means and what to do, plus the error JSON shape, request ids for support tickets, and which errors to retry.

This page lists every API error code the Tokens gateway returns, what each one means, and whether to retry. Branch on the `code` field in your code; messages are for humans and can change.

## Error JSON shape

Errors raised by the gateway on OpenAI-style endpoints (`/v1/chat/completions`, `/v1/completions`, `/v1/responses`, `/v1/embeddings`, `/v1/models`) look like OpenAI's:

```json
{
  "error": {
    "message": "Prepaid wallet balance is insufficient for this request. Top up your wallet in the dashboard: https://tokens.bd/dashboard/billing",
    "type": "insufficient_quota",
    "code": "insufficient_credits",
    "param": null,
    "request_id": "8f0c7a4e-2b1d-4c55-9a51-3f7e2d9b6c10"
  }
}
```

| Field        | Notes                                                                                                                                                                             |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`       | Stable, machine-readable. Use this.                                                                                                                                               |
| `type`       | Broad class from the status: `invalid_request_error`, `authentication_error`, `insufficient_quota`, `permission_denied_error`, `rate_limit_error` or `server_error`. |
| `message`    | Human-readable. Billing errors include a link to [billing](/dashboard/billing).                                                                                                   |
| `request_id` | Same value as the `x-tokens-request-id` header. Also in the `x-tokens-request-id` header on every response.                                                                          |

On `/v1/messages` and `/v1/messages/count_tokens`, every error uses Anthropic's shape instead, whether Tokens or the upstream provider raised it: `{"type": "error", "error": {"type": "...", "message": "...", "code": "..."}, "request_id": "..."}`. Tokens adds `code` to Anthropic's shape, so you can still branch on the codes below; only a provider's explanation of a mistake in your request comes without one. Upstream error messages are replaced with a generic message so provider internals don't leak, except that explanation, which is cleaned of provider names and passed on so you can fix the request; the HTTP status and `code` still tell you the category.

## Error code reference

| Status | Code | When | What to do |
| --- | --- | --- | --- |
| 400 | `invalid_request` | No `model` field (or no `Content-Type: application/json`), or `n` outside 1 to 4. Also when a provider rejects the request itself: then its explanation, its status and its own code (when it gave one) are passed on | Fix the request. For a provider's rejection, check the model supports the parameters you sent |
| 400 | `model_not_available` | The model is in the catalog but has no price set yet, so it can't be served | Pick another model from `GET /v1/models`, and report it |
| 400 | `endpoint_not_supported_for_model` | None of the providers serving this model can answer this endpoint (for example `/v1/responses`, `/v1/completions` or embeddings on a chat model), known from the routing or because every provider said so. The message names the model and the endpoint | Don't retry. Use an endpoint the model supports (often `/v1/chat/completions`), or pick another model |
| 400 | `context_length_exceeded` | The prompt plus `max_tokens` is longer than the model's context window on every provider tried. The message is the provider's explanation, and a provider's own code can stand in for this one | Shorten the input or lower `max_tokens` |
| 401 | `missing_api_key` | No `Authorization: Bearer` or `x-api-key` header | Set `TOKENS_API_KEY` in the environment that runs the tool |
| 401 | `invalid_api_key` | Key not recognized: mistyped, deleted, or a rotated key's old secret that has stopped | Recopy the key or create a new one |
| 402 | `insufficient_credits` | Plan credits and wallet can't cover the request's prompt and a short answer (on **Wallet only**, the wallet alone) | Top up or renew in [billing](/dashboard/billing), or send a shorter prompt |
| 402 | `no_funding` | No active plan and no wallet balance | Subscribe or add funds |
| 402 | `outstanding_debt` | Earlier usage left an amount owed that your balance couldn't cover | Top up to repay it; with a plan, its next credits repay it when it renews |
| 402 | `member_cap_reached` | On a team: the monthly spend cap the team set for you is reached | Ask a team owner to raise it |
| 402 | `bonus_model_not_allowed` | Only your sign-up bonus could pay, and the bonus can't be used for this model | Subscribe or top up, or use a model the bonus covers |
| 403 | `key_inactive` | Key suspended | Use another key, or ask support why it was suspended |
| 403 | `key_expired` | Key past its expiry date | Create a new key |
| 403 | `account_suspended` | Account suspended | Contact [support](/docs/support) |
| 403 | `model_not_allowed_on_key` | Model not in this key's allowed list | Use an allowed model or another key |
| 403 | `monthly_spend_cap_exceeded` | Key's monthly spend cap reached (the check includes this request's worst-case cost) | Lower `max_tokens`, wait for the new month, or create a key with a higher cap (a key's cap can't be changed) |
| 403 | `tier_permission_denied` | Your plan doesn't include this model and you have no wallet balance | Upgrade, or add wallet funds for pay-as-you-go |
| 403 | `ip_blocked` | Requests from your network are blocked by the platform | Contact [support](/docs/support) if you think this is a mistake |
| 403 | `forbidden` | The gateway refused the request for a reason it has no specific code for | Contact [support](/docs/support) with the request id |
| 404 | `model_not_found` | Model id unknown or inactive. Also when a provider says something you named (a stored response, a file) doesn't exist, with its own code when it gave one | Check the exact id with `GET /v1/models`, or the id you referred to |
| 404 | `unsupported_endpoint` | Path or method isn't one of the supported endpoints | See [models and usage](/docs/models-and-usage) for the endpoint list |
| 404 | `anthropic_protocol_disabled` | The Messages API (`/v1/messages`) is switched off on this deployment | Use Chat Completions instead |
| 413 | `request_entity_too_large` | Body over 10 MB | Trim context or attachments |
| 429 | `rate_limited` | Your plan's requests-per-minute limit is reached, or one key sent more than 600 token counting requests in a minute | Wait `Retry-After` seconds |
| 429 | `concurrency_limit` | Too many requests running at once on your account | Wait `Retry-After` or reduce parallelism |
| 429 | `emergency_rate_limit` | The platform has a temporary per-account request cap in place, and you are over it | Slow down and wait `Retry-After` seconds |
| 429 | `window_exhausted` | A plan usage limit (the 5-hour session, the weekly or the monthly ceiling) is reached | Wait for the reset (`Retry-After`), let your wallet pay with **What pays** set to Auto, or upgrade the plan |
| 429 | `model_limit_reached` | This model's allowance on your plan is used up for the billing period; your other models still work | Switch models, or wait for the reset (`Retry-After`, shown as a date in the message) |
| 429 | `free_limit_reached` | You've used this free model's request allowance | Wait for the reset in `Retry-After` (absent when the allowance never resets), or use another model |
| 429 | `rate_limit_exceeded` | The model's providers rate limited the gateway and no other provider could take the request | Retry with backoff; honor `Retry-After` if present |
| 500 | `lookup_failed`, `admission_error`, `catalog_error`, `usage_unavailable`, `inference_failed` | Internal error on our side | Retry once or twice with backoff, then contact support |
| 502 | `upstream_unreachable` | No provider for this model gave a usable answer: connection errors, server errors from several providers, or streams that failed before their first token | Retry with backoff; check [status](/status) |
| 502 | `upstream_invalid_response` | A provider answered with something that isn't an API response (a web page) | Retry with backoff; contact support if it keeps happening |
| 5xx | `upstream_error` | The only provider tried returned a server error; its status is passed on | Retry with backoff |
| 503 | `upstream_unavailable` | Every provider for this model failed for a reason on their side (refused credentials, an empty balance, the model missing there) | Retry with backoff; check [status](/status) |
| 503 | `upstream_overloaded` | The model's providers are overloaded | Retry with backoff |
| 503 | `no_upstream_available` | No provider is configured for this model right now | Try another model; check [status](/status) |
| 503 | `model_not_priced` | The model has no price configured, so it can't be billed | Try another model and report it |
| 503 | `service_paused` | The platform has paused API access while it deals with a problem; `Retry-After` is 300 seconds | Retry after `Retry-After`; check [status](/status) |
| 504 | `upstream_timeout` | No provider answered in time. A provider with another one behind it gets 30 s to start a stream (60 s for a non-streaming answer, 15 s for embeddings) before the next one is tried; the last gets 120 s of silence before a stream's first token, or 600 s to start a non-streaming answer. The operator can change the first two | Retry once; stream long answers, or send a smaller request |

The table is generated from the gateway's own list of codes, so the gateway never sends a code missing here; only a provider's own code can come through on a request it rejected, as the 400 and 404 rows say. Branch on `code`, not on the message.

Before returning anything to you, the gateway already tries the model's next provider when one fails for a reason on its side: a 5xx, a 429, a 401, 402 or 403 about the provider's own account, a model missing there, a timeout, a connection error or a web page instead of an answer. An upstream error you see means every provider tried for that model failed.

### Errors inside a stream

A stream that has started has already sent its 200, so a failure after that arrives as the stream's last event instead of a status. On `/v1/chat/completions` and `/v1/completions` it is a `data:` object with an `error` holding the code below, followed by `data: [DONE]`; on `/v1/messages` an `event: error` with type `api_error`; on `/v1/responses` a `response.failed` event with code `server_error`.

| Code | When | What to do |
| --- | --- | --- |
| `upstream_stream_stalled` | The provider sent nothing for longer than the stall limit: 240 s once content has started (the operator can change it), 600 s before that | The answer is incomplete. Retry if the partial output isn't usable; a retry bills the prompt again |
| `upstream_stream_ended_early` | The provider's stream ended without its final event | The answer is incomplete. Retry if the partial output isn't usable; a retry bills the prompt again |
| `upstream_stream_reset` | The connection to the provider broke mid-stream | The answer is incomplete. Retry if the partial output isn't usable; a retry bills the prompt again |

A streaming request whose providers take more than a few seconds to answer gets its 200 and the SSE headers early, so that proxies don't cut the quiet connection. If no provider then answers, the error from the table above arrives the same way, as one error event with the same `code`. When there is a wait, it is the `retry_after` field in the body, since the headers have already gone.

## Response headers

The gateway adds these headers to `/v1` responses. Headers from the model's provider are not passed on, apart from the content type, `cache-control` and `retry-after`.

| Header | Sent on | Value |
| --- | --- | --- |
| `x-tokens-request-id` | Every response, success or error | The gateway's id for this request (a UUID), always generated by Tokens. Quote it to support |
| `x-request-id` | Every response | The `x-request-id` you sent, or the same id as `x-tokens-request-id` if you sent none |
| `x-trace-id` | Inference responses, and errors once the request was admitted | The same value as `x-tokens-request-id` |
| `x-tokens-attempts` | Inference responses, and errors once providers were tried. Not on a stream whose headers went out before a provider answered | How many providers were tried for this request: `1` when the first one answered, more after a failover |
| `x-tokens-paid-by` | Admitted inference requests | What pays for this request: `plan`, `wallet` or `free` |
| `x-tokens-wallet-reason` | When the wallet pays on an account that has a plan | Why the wallet pays: `limit` (a usage limit was reached), `credits` (plan credits ran out), `model_limit` (the model's allowance was used up) or `manual` (Wallet only) |
| `x-tokens-free-requests-limit` | Requests a model's free access paid for | How many free requests the account gets on this model |
| `x-tokens-free-requests-remaining` | Requests a model's free access paid for | How many of them are left after this one |
| `x-tokens-model-alias` | Requests that named a curated alias such as `auto` or `best-value` | The curated name the request sent |
| `x-tokens-resolved-model` | Requests that named a curated alias | The model that served the request and that it was billed as (also in the answer's `model` field) |
| `x-ratelimit-limit-requests` | Admitted inference requests, and the 429 `rate_limited` error | Your requests-per-minute limit (counted per person, all keys together; 10 in the playground) |
| `x-ratelimit-remaining-requests` | Admitted inference requests, and the 429 `rate_limited` error | Requests left in the current minute, after this one |
| `x-ratelimit-reset-requests` | Admitted inference requests, and the 429 `rate_limited` error | Time until the minute's count starts again, in seconds with an `s` (`23s`) |
| `x-tokens-window-type` | Admitted requests on a plan with usage limits, once a limit's window has started. Not on **Wallet only** | The usage limit with the least left: `session_5h` (5-hour session), `weekly` or `monthly` ceiling |
| `x-tokens-window-unit` | With `x-tokens-window-type` | What the limit counts: `usd` (usage value in USD) or `requests` |
| `x-tokens-window-limit` | With `x-tokens-window-type` | The limit's size, in its unit |
| `x-tokens-window-remaining` | With `x-tokens-window-type` | What is left of it, in its unit, as the dashboard shows it; `0` when it is reached. This request counts once it ends |
| `x-tokens-window-reset` | With `x-tokens-window-type` | When the limit resets: an ISO 8601 time in UTC |
| `x-tokens-credits-remaining` | Admitted requests that plan credits pay for, or that the wallet pays for because the credits can't. Not on **Wallet only**, past a reached limit, or for a free model or token allowance | Plan credits available now, in USD: what is left this period minus what running requests hold, this one included (the dashboard's figure) |
| `x-tokens-wallet-remaining` | Admitted requests that plan credits or the wallet pay for. Not for a free model or token allowance | Wallet available now, in USD: balance plus any sign-up bonus, minus what running requests hold, this one included (the dashboard's figure) |
| `x-tokens-deprecation` | Inference requests, and errors once the model was found, for a model with a retirement date | When this model id retires: an ISO 8601 time in UTC. Move to another model before then; the model's page names the one to use |
| `sunset` | With `x-tokens-deprecation` | The same time as an HTTP date (RFC 8594) |
| `link` | With `x-tokens-deprecation`, when the model has a successor | The model to move to: `</models/<model id>>; rel="successor-version"`, its page on this site |
| `x-tokens-estimated` | `/v1/messages/count_tokens` answered by the gateway's own estimate | `true`: the count is an estimate, not the provider's |
| `retry-after` | 429 errors, `service_paused`, and provider errors that carried one | Seconds to wait before retrying |
| `access-control-allow-origin` | Every response, and the `OPTIONS` preflight | `*`: browser code may read the answer. `access-control-expose-headers` lists the headers above. Keep keys on a server: a key shipped in a web page is public |

## Request ids and support tickets

Every response, success or error, carries `x-tokens-request-id`, the gateway's id for the request, and `x-request-id`. Sending your own `x-request-id` lets you correlate our id with your logs. To read the header with the OpenAI Python SDK:

```python
raw = client.chat.completions.with_raw_response.create(
    model="deepseek/deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "ping"}],
)
print(raw.headers.get("x-tokens-request-id"))
completion = raw.parse()
```

With curl, add `-i` to print headers. When you open a ticket in [support](/dashboard/support), include the `x-tokens-request-id`, the time (with timezone), the endpoint, the model and the status code. Never include the API key. We store usage metadata by request id, not prompt content, so the id is what lets us find your request. More in [support](/docs/support).

## Retry guidance

| Retry | Codes |
| --- | --- |
| Yes, after `Retry-After` | `rate_limited`, `concurrency_limit`, `emergency_rate_limit`, `rate_limit_exceeded`, `service_paused` |
| Yes, with exponential backoff | `lookup_failed`, `admission_error`, `catalog_error`, `usage_unavailable`, `inference_failed`, `upstream_unreachable`, `upstream_invalid_response`, `upstream_error`, `upstream_unavailable`, `upstream_overloaded`, `upstream_timeout`, `upstream_stream_stalled`, `upstream_stream_ended_early`, `upstream_stream_reset` |
| Only after the reset time, not in a loop (`Retry-After` can be days) | `window_exhausted`, `model_limit_reached`, `free_limit_reached` |
| No, fix something first | `invalid_request`, `model_not_available`, `endpoint_not_supported_for_model`, `context_length_exceeded`, `missing_api_key`, `invalid_api_key`, `insufficient_credits`, `no_funding`, `outstanding_debt`, `member_cap_reached`, `bonus_model_not_allowed`, `key_inactive`, `key_expired`, `account_suspended`, `model_not_allowed_on_key`, `monthly_spend_cap_exceeded`, `tier_permission_denied`, `ip_blocked`, `forbidden`, `model_not_found`, `unsupported_endpoint`, `anthropic_protocol_disabled`, `request_entity_too_large`, `no_upstream_available`, `model_not_priced` |

Backoff that works in practice: start around 1 second, double each attempt, add random jitter, cap at 30 seconds, and stop after 4 or 5 attempts. If `Retry-After` is present, wait at least that long. A retry is a new request and is billed if it succeeds, and the OpenAI and Anthropic SDKs already retry some of these errors on their own, so check `max_retries` before stacking your own loop on top. A full backoff example is in [rate limits](/docs/rate-limits), and agent-specific fixes are in [troubleshooting](/docs/troubleshooting).

---
Page: https://tokens.bd/docs/errors
