Skip to content

4 Uncensored LLM model added, currently available for only pay-as-you-go users.See Models

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.

Last updated 17 Nov 2026

On this page

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"
  }
}
FieldNotes
codeStable, machine-readable. Use this.
typeBroad class from the status: invalid_request_error, authentication_error, insufficient_quota, permission_denied_error, rate_limit_error or server_error.
messageHuman-readable. Billing errors include a link to billing.
request_idSame 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#

StatusCodeWhenWhat to do
400invalid_requestNo 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 onFix the request. For a provider's rejection, check the model supports the parameters you sent
400model_not_availableThe model is in the catalog but has no price set yet, so it can't be servedPick another model from GET /v1/models, and report it
400endpoint_not_supported_for_modelNone 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 endpointDon't retry. Use an endpoint the model supports (often /v1/chat/completions), or pick another model
400context_length_exceededThe 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 oneShorten the input or lower max_tokens
401missing_api_keyNo Authorization: Bearer or x-api-key headerSet TOKENS_API_KEY in the environment that runs the tool
401invalid_api_keyKey not recognized: mistyped, deleted, or a rotated key's old secret that has stoppedRecopy the key or create a new one
402insufficient_creditsPlan 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, or send a shorter prompt
402no_fundingNo active plan and no wallet balanceSubscribe or add funds
402outstanding_debtEarlier usage left an amount owed that your balance couldn't coverTop up to repay it; with a plan, its next credits repay it when it renews
402member_cap_reachedOn a team: the monthly spend cap the team set for you is reachedAsk a team owner to raise it
402bonus_model_not_allowedOnly your sign-up bonus could pay, and the bonus can't be used for this modelSubscribe or top up, or use a model the bonus covers
403key_inactiveKey suspendedUse another key, or ask support why it was suspended
403key_expiredKey past its expiry dateCreate a new key
403account_suspendedAccount suspendedContact support
403model_not_allowed_on_keyModel not in this key's allowed listUse an allowed model or another key
403monthly_spend_cap_exceededKey'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)
403tier_permission_deniedYour plan doesn't include this model and you have no wallet balanceUpgrade, or add wallet funds for pay-as-you-go
403ip_blockedRequests from your network are blocked by the platformContact support if you think this is a mistake
403forbiddenThe gateway refused the request for a reason it has no specific code forContact support with the request id
404model_not_foundModel 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 oneCheck the exact id with GET /v1/models, or the id you referred to
404unsupported_endpointPath or method isn't one of the supported endpointsSee models and usage for the endpoint list
404anthropic_protocol_disabledThe Messages API (/v1/messages) is switched off on this deploymentUse Chat Completions instead
413request_entity_too_largeBody over 10 MBTrim context or attachments
429rate_limitedYour plan's requests-per-minute limit is reached, or one key sent more than 600 token counting requests in a minuteWait Retry-After seconds
429concurrency_limitToo many requests running at once on your accountWait Retry-After or reduce parallelism
429emergency_rate_limitThe platform has a temporary per-account request cap in place, and you are over itSlow down and wait Retry-After seconds
429window_exhaustedA plan usage limit (the 5-hour session, the weekly or the monthly ceiling) is reachedWait for the reset (Retry-After), let your wallet pay with What pays set to Auto, or upgrade the plan
429model_limit_reachedThis model's allowance on your plan is used up for the billing period; your other models still workSwitch models, or wait for the reset (Retry-After, shown as a date in the message)
429free_limit_reachedYou've used this free model's request allowanceWait for the reset in Retry-After (absent when the allowance never resets), or use another model
429rate_limit_exceededThe model's providers rate limited the gateway and no other provider could take the requestRetry with backoff; honor Retry-After if present
500lookup_failed, admission_error, catalog_error, usage_unavailable, inference_failedInternal error on our sideRetry once or twice with backoff, then contact support
502upstream_unreachableNo provider for this model gave a usable answer: connection errors, server errors from several providers, or streams that failed before their first tokenRetry with backoff; check status
502upstream_invalid_responseA provider answered with something that isn't an API response (a web page)Retry with backoff; contact support if it keeps happening
5xxupstream_errorThe only provider tried returned a server error; its status is passed onRetry with backoff
503upstream_unavailableEvery 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
503upstream_overloadedThe model's providers are overloadedRetry with backoff
503no_upstream_availableNo provider is configured for this model right nowTry another model; check status
503model_not_pricedThe model has no price configured, so it can't be billedTry another model and report it
503service_pausedThe platform has paused API access while it deals with a problem; Retry-After is 300 secondsRetry after Retry-After; check status
504upstream_timeoutNo 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 twoRetry 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.

CodeWhenWhat to do
upstream_stream_stalledThe provider sent nothing for longer than the stall limit: 240 s once content has started (the operator can change it), 600 s before thatThe answer is incomplete. Retry if the partial output isn't usable; a retry bills the prompt again
upstream_stream_ended_earlyThe provider's stream ended without its final eventThe answer is incomplete. Retry if the partial output isn't usable; a retry bills the prompt again
upstream_stream_resetThe connection to the provider broke mid-streamThe 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.

HeaderSent onValue
x-tokens-request-idEvery response, success or errorThe gateway's id for this request (a UUID), always generated by Tokens. Quote it to support
x-request-idEvery responseThe x-request-id you sent, or the same id as x-tokens-request-id if you sent none
x-trace-idInference responses, and errors once the request was admittedThe same value as x-tokens-request-id
x-tokens-attemptsInference responses, and errors once providers were tried. Not on a stream whose headers went out before a provider answeredHow many providers were tried for this request: 1 when the first one answered, more after a failover
x-tokens-paid-byAdmitted inference requestsWhat pays for this request: plan, wallet or free
x-tokens-wallet-reasonWhen the wallet pays on an account that has a planWhy 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-limitRequests a model's free access paid forHow many free requests the account gets on this model
x-tokens-free-requests-remainingRequests a model's free access paid forHow many of them are left after this one
x-tokens-model-aliasRequests that named a curated alias such as auto or best-valueThe curated name the request sent
x-tokens-resolved-modelRequests that named a curated aliasThe model that served the request and that it was billed as (also in the answer's model field)
x-ratelimit-limit-requestsAdmitted inference requests, and the 429 rate_limited errorYour requests-per-minute limit (counted per person, all keys together; 10 in the playground)
x-ratelimit-remaining-requestsAdmitted inference requests, and the 429 rate_limited errorRequests left in the current minute, after this one
x-ratelimit-reset-requestsAdmitted inference requests, and the 429 rate_limited errorTime until the minute's count starts again, in seconds with an s (23s)
x-tokens-window-typeAdmitted requests on a plan with usage limits, once a limit's window has started. Not on Wallet onlyThe usage limit with the least left: session_5h (5-hour session), weekly or monthly ceiling
x-tokens-window-unitWith x-tokens-window-typeWhat the limit counts: usd (usage value in USD) or requests
x-tokens-window-limitWith x-tokens-window-typeThe limit's size, in its unit
x-tokens-window-remainingWith x-tokens-window-typeWhat 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-resetWith x-tokens-window-typeWhen the limit resets: an ISO 8601 time in UTC
x-tokens-credits-remainingAdmitted 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 allowancePlan 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-remainingAdmitted requests that plan credits or the wallet pay for. Not for a free model or token allowanceWallet available now, in USD: balance plus any sign-up bonus, minus what running requests hold, this one included (the dashboard's figure)
x-tokens-deprecationInference requests, and errors once the model was found, for a model with a retirement dateWhen 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
sunsetWith x-tokens-deprecationThe same time as an HTTP date (RFC 8594)
linkWith x-tokens-deprecation, when the model has a successorThe 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 estimatetrue: the count is an estimate, not the provider's
retry-after429 errors, service_paused, and provider errors that carried oneSeconds to wait before retrying
access-control-allow-originEvery 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, 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.

Retry guidance#

RetryCodes
Yes, after Retry-Afterrate_limited, concurrency_limit, emergency_rate_limit, rate_limit_exceeded, service_paused
Yes, with exponential backofflookup_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 firstinvalid_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, and agent-specific fixes are in troubleshooting.

Was this page helpful?

Still stuck? Open a support ticket

Need help configuring your agent?

Test your connection with the connection tester, or create an API key.