Errors and rate limits

Error format

Errors use OpenAI’s format. The message ends with a request id; include it when you contact support.

{
  "error": {
    "message": "Invalid token (request id: 20261025091530123456789...)",
    "type": "new_api_error",
    "param": "",
    "code": ""
  }
}

On /v1/messages, errors raised while the request is processed come in Anthropic’s format, {"type": "error", "error": {"type": "...", "message": "..."}}. Key and rate-limit errors are checked before the request is read and come in the OpenAI format on every endpoint; both formats carry the HTTP status.

Status codes

Status	code	Message (start)	What to do
400	invalid_request	<model> does not support tool calling (function calling).	Send the request without tools, or use a model with tool calling.
400	invalid_request	depends on the field	Fix the request body.
401		Invalid token	The key is missing, wrong, disabled, expired, or its spending limit is used up. Check it in the console under API Keys.
403	insufficient_user_quota	insufficient balance: ...	Top up, raise the key’s spending limit, or lower max_tokens. See below.
403		This token has no access to model <model>	The key’s model allow-list does not include this model.
429	concurrency_limit_exceeded	Too many requests in progress for this account: ...	Wait for a request to finish. See limits.
429		Rate limit reached: ...	Slow down. See limits.
503	model_not_found	No available channel for model <model> under group <group> (distributor)	Check the model name; if it is right, no provider can serve it for this key’s group right now. Retry later.
5xx		varies	Every provider for the model failed. Retry with backoff.

The full messages, as TOKEN sends them:

400  meta-llama/llama-4-maverick does not support tool calling (function calling). Send the request without tools, or choose a model that supports them (the models page lists which do)
401  Invalid token
403  This token has no access to model zai-org/glm-5.3
403  insufficient balance: $0.0000 left. Top up your credit to continue
403  insufficient balance: moonshotai/kimi-k3 needs at least $0.0041 for a reply of 256 tokens; this key can spend $0.0012. Top up your credit or raise the key's spending limit
403  insufficient balance: this request needs $0.0520 reserved and $0.0300 is left. Top up your credit or lower max_tokens
429  Too many requests in progress for this account: at most 10 at a time. Wait for one to finish, then try again.
429  Rate limit reached: at most 60 requests (failed ones included) per 1 minute(s) for this account. Wait a moment, then try again.
429  Rate limit reached: at most 60 successful requests per 1 minute(s) for this account. Wait a moment, then try again.
503  No available channel for model zai-org/glm-5.3 under group us-eu-hosted (distributor)
5xx  The service is temporarily unavailable. Please retry in a few seconds.

Dollar amounts and model names are examples; each message also ends with (request id: ...). The link in the 400 message is shortened by the relay’s masking of URLs in error messages; it points to the models page.

Rate limits

Limits apply per account: all keys of an account share them.

Limit	Value	Error
Requests in flight (started and not yet finished, streams included)	10	429, code concurrency_limit_exceeded
Requests per minute, failed ones included	60: up to 60 at once, then one more per second	429, “Rate limit reached: at most 60 requests (failed ones included) …”
Successful requests per rolling minute	60	429, “Rate limit reached: at most 60 successful requests …”

• A request refused with 429 still counts toward the 60 requests per minute, so retrying in a tight loop keeps you limited. Back off instead.
• Long streamed replies hold one of the 10 slots until they finish. For parallel work (batch jobs, agents with sub-agents), cap your own concurrency below 10.

Balance and the output reservation

TOKEN is prepaid, so a request must be paid for before it runs:

1. Reserve. Before the request is sent to a provider, TOKEN reserves its worst-case cost: the estimated input plus the maximum output. The maximum output is your max_tokens (or max_completion_tokens, max_output_tokens), or, if you set none, the model’s maximum output from its model page.
2. Lower if needed. If your balance, or the key’s spending limit when it is lower, cannot pay for that maximum, TOKEN lowers the request’s maximum output to what they can pay. The reply may then end early with finish_reason: "length".
3. Refuse if too small. If they cannot pay for even a 256-token reply, the request is refused with 403 (“needs at least … for a reply of 256 tokens”). A request whose own max_tokens is below 256 needs only that.
4. Settle. When the reply is done, you pay for the tokens actually used (usage), and the rest of the reservation is released at once.

So a request without max_tokens to a model with a large maximum output reserves a lot, briefly. With a small balance, or many requests in parallel, set max_tokens to what you need: the reservations stay small and requests are not lowered or refused.

Retrying

Error	Retry?
429	Yes, after a delay: exponential backoff with jitter (for example 1 s, 2 s, 4 s, up to 30 s).
500, 502, 503, 504 and network errors	Yes, with backoff, a few times. TOKEN has already tried the model’s other providers.
400, 401, 403	No. Fix the request, the key or the balance first.

A retried request is a new request and is billed again if it completes; TOKEN does not deduplicate requests.

OpenAI’s SDKs retry 429 and 5xx responses twice by default, with backoff. To allow more attempts:

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.thetoken.dev/v1", api_key=os.environ["TOKEN_API_KEY"], max_retries=5)

import OpenAI from 'openai'

const client = new OpenAI({ baseURL: 'https://api.thetoken.dev/v1', apiKey: process.env.TOKEN_API_KEY, maxRetries: 5 })