Core Guides
Handle API errors
Read error codes, retry only when useful, and keep the Request ID
Handle errors by HTTP status and code. The message is written for people and can change without notice.
Chat Completions and Responses use an OpenAI-style error object. Anthropic Messages and Gemini keep their own error formats, so do not use one parser for every TokenLab API.
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}Only message and type are always present in OpenAI-compatible errors created by TokenLab. Other fields appear when they are relevant.
Status codes
| Status | Meaning | Typical action |
|---|---|---|
400 | A field, model ID, or input is invalid | Fix the request; do not repeat it unchanged |
401 | API key is missing, invalid, expired, or revoked | Replace the key |
402 | Balance or API-key limit is too low | Top up, raise the limit, or reduce the request |
403 | This key cannot use the resource or model, or the account is restricted | Change the key's permissions or model, or contact support |
404 | Resource does not exist or is no longer available | Check the ID and the API key that created it |
409 | The Idempotency-Key was already used: with a different request body (idempotency_conflict), or for a request whose result TokenLab cannot return (idempotency_replay_unavailable, idempotent_response_not_replayable). TokenLab did not run the request again | Use a new key for a new request. To decide whether to retry with the same key, see Retry safely with an idempotency key |
413 | Request or uploaded file is too large | Reduce the input to the documented model or endpoint limit |
429 | Request limit reached | Wait for Retry-After |
500–504 | Service unavailable or network failure | Retry only when retryable is true; respect retry_after and limit attempts |
Common error codes
| Code | What it means | What to change |
|---|---|---|
invalid_api_key | The API key is missing, invalid, inactive, or revoked | Check the Authorization header and key value |
expired_api_key | The key has expired | Create or select an active key |
insufficient_balance | The account balance cannot cover the request | Add funds, reduce the request, or choose a lower-priced model |
quota_exceeded | The API key reached its own limit | Increase that key's limit or use a different authorized key |
model_not_allowed | The key cannot use the requested model | Update the key's model list or choose an allowed model |
user_suspended, account_restricted | HTTP 403. The account cannot use the API | Contact support with the Request ID |
invalid_delivery_policy | HTTP 400. The X-TokenLab-Delivery-Policy header is not auto, verified, or official | Send one of the three values, or remove the header |
model_not_found | The model ID is unknown or unavailable | Read /v1/models and use a current model ID |
context_length_exceeded | Input is longer than the model accepts | Remove history or choose a model with a larger context window |
missing_required_parameter | A required field is missing. param names it, for example model on audio and image requests, which have no default model | Send the field that param names |
invalid_value | A field has a value that the model does not accept, for example a reasoning_effort value. The message lists the accepted values | Use one of the listed values |
invalid_response_format_type | HTTP 400. response_format is an object without a usable type, or with a type this endpoint does not accept. param is response_format | Set response_format.type to text, json_object, or json_schema; with json_schema, also send json_schema.name and json_schema.schema |
invalid_image_url | TokenLab cannot use an image URL: it is not a valid HTTP(S) URL or image data URI, or the image host did not return the image. param names the field | Send a public HTTPS image URL or a supported data URI |
content_policy_violation | HTTP 400. A model provider's safety check rejected the prompt or the input media. The request was not charged, and retryable is false. On an Official route, upstream.code carries the provider's own code, such as moderation_blocked or data_inspection_failed | Review the prompt and the media, then send a revised request. See Content safety rejections |
unsupported_model_capability | No route of the selected Delivery tier supports a request parameter, such as the operation, resolution, aspect_ratio, duration, an input media field, web_search_options, or max_tokens. The message names each parameter that did not match and, when the model publishes them, the supported values | Remove or change the parameter, or choose another Delivery tier or model; do not repeat the request unchanged |
unpriceable_selection | The video request leaves out a selector that its price depends on, so TokenLab cannot price it. param names the selector | Set the field that param names |
model_pricing_unavailable | HTTP 503. The request is valid, but TokenLab cannot price this combination of model and operation on the routes the request can use. The request was not charged, and retryable is false | Do not repeat the request unchanged; choose another model or operation, or contact support with the Request ID |
idempotency_conflict | HTTP 409. The Idempotency-Key belongs to a different request. TokenLab did not run this request | Send a new request with a new key |
idempotency_replay_unavailable | HTTP 409. The Idempotency-Key was already used, and TokenLab has no result to return for it. TokenLab did not run this request again | If the first request can still be running, wait and retry with the same key. Otherwise send a new key. See Retry safely with an idempotency key |
idempotent_response_not_replayable | HTTP 409. The Idempotency-Key belongs to a create request whose task already finished, and TokenLab cannot return the original create response. The top level of the response body includes task_id, next to error. TokenLab did not run this request again | Do not repeat the request with this key. Send a new key only if you want a new task |
rate_limit_exceeded | Too many requests were sent in the current window | Wait for Retry-After |
all_channels_failed | The selected model cannot serve this request | Retry only when retryable is true; respect retry_after and limit attempts |
timeout_error | The request did not finish in time | Retry only when the operation is safe to repeat |
A 503 all_channels_failed or 503 delivery_tier_unavailable does not always mean a temporary outage. If the requested operation has no supply in the selected Delivery tier, retryable is false and retry_after is omitted. Do not repeat the same request. Check the operation and Delivery availability with GET /v1/models before selecting another model. Similar names do not prove availability; unverified alternatives are omitted.
Some OpenAI-compatible errors include optional did_you_mean, suggestions, alternatives, hint, retryable, or retry_after fields. See Errors agents can act on.
When a request ran on an Official route and the upstream service rejected the request itself, such as an input it does not accept or a content policy decision, the error also carries upstream: the upstream's message as reported, plus code and source (the upstream service name) when known. Anthropic Messages and Gemini errors carry the same object inside their own error. Keep branching on code and type; upstream.code values are defined by the upstream service and may change.
Content safety rejections
Safety checks run at the model provider, not at TokenLab. When a check rejects a request, the response is 400 with code content_policy_violation and retryable set to false. The body carries type invalid_request_error, code content_policy_violation, retryable false, and a hint; on an Official route it also carries upstream with the provider's source, code, and message.
Provider codes that TokenLab reports this way include moderation_blocked, content_moderated, data_inspection_failed, failedoperation.moderationfailed, prompt_blocked, sensitive_content_detected, sensitive_words_detected, and prohibited_content. Providers that describe the same decision in prose, for example "request blocked by moderation policy" or "this request did not pass the content safety check", get the same code.
Three things follow from who made the decision:
- The request was not charged. The rejection happens before billable usage.
- Repeating it unchanged returns the same rejection. Do not put these requests in a retry loop, and do not treat
upstream.messageas a temporary failure. - TokenLab does not send the same request to another provider to avoid the decision. The decision applies to the request, not to the route it ran on.
To get a request through, change the request: rewrite the prompt, or remove the part of the media that was flagged. Requests that carry media are screened on the prompt and on the media, so review both. Each provider publishes its own policy and applies it to its own models, so the same prompt can pass on one model and be rejected on another; upstream.source names the provider that said no. Read that provider's policy before you choose another model: changing provider is how you find a policy that accepts your use, not how you get around one.
If you believe the rejection is wrong, contact support with the Request ID, the model ID, and upstream.code. Never send the private media or the complete prompt.
Retry decisions
| Error | Repeat the same request? |
|---|---|
400, 401, 402, 403, 404, 413 | No. Change the request, credentials, balance, permissions, or input. |
429 | Yes, after the server-provided delay. |
500–504 | Retry only when retryable is true; respect retry_after and limit attempts |
| Connection closed before any response | Yes, when the request is listed in Retry safely with an idempotency key and has an Idempotency-Key: send it again with the same key and body. Otherwise, first check whether a task or side effect already exists. |
| Stream interrupted after output arrived | Do not call it a complete response. Repeating may generate different output or a second charge. |
For image, video, music, 3D, and Worlds creation, save the task ID as soon as it is returned. If a create request times out, send it again with the same Idempotency-Key and body to get the original task. Without a key, check the task record before sending another create request.
Retry safely with an idempotency key
A timeout or a closed connection does not tell you whether TokenLab ran the request. Add an Idempotency-Key header to the requests listed below. Then a retry of the same request cannot run or charge it a second time.
- Use a new unique value for each operation, for example a UUID. A key can have up to 255 characters. TokenLab ignores a longer key, and the request then has no idempotency protection: a retry runs and is charged again.
POST /v1/messages/batchesis different: it rejects a key longer than 256 characters with400. - Save the key with your own job record before you send the request.
- When you retry, send the same API key, the same
Idempotency-Key, and the same body. - After any response other than
409withidempotency_replay_unavailable, do not use that key again. Send any new attempt with a new key. - Turn off SDK retries (
max_retries=0), so that your code decides when to reuse a key.
Without the header, every retry is a new request.
Requests that create a task
These create requests accept Idempotency-Key:
POST /v1/videos/generations,POST /v1/music/generations,POST /v1/3d/generations, andPOST /v1/worlds/generationsPOST /v1/images/generationsandPOST /v1/images/editswhen they return a taskPOST /v1/responseswith"background": truePOST /v1/messages/batches
If a create request times out, send it again without changes. TokenLab returns the result of the original create request and does not create, dispatch, or charge a second task. Usually the result is the original task with the same id (for Responses, the original response object), and you continue to poll it. For video, music, 3D, Worlds, and image tasks, the result can also be the original error when the first create request failed. If such a task already finished and TokenLab has no stored create response, the retry returns 409 with code idempotent_response_not_replayable, and the top level of the response body includes task_id.
If you send a different body with a key that TokenLab already accepted, TokenLab rejects the request and does not create a task. Video, music, 3D, and Worlds create requests return 409 with code idempotency_conflict. Message Batches returns 409 with error type conflict_error. For image tasks and for Responses requests with background: true, the status code and error code for this case are not guaranteed. Do not retry the request with the same key.
Chat Completions, Responses, and Messages
POST /v1/chat/completions, POST /v1/responses without background, and POST /v1/messages run a request with a given key only once. A retry with the same key gets one of these results:
| Situation | Result |
|---|---|
| The first request is still running | 409 with code idempotency_replay_unavailable |
| The first request finished after your client disconnected. The request was not streamed, the result is 1 MB or smaller, and you retry with the same body within 24 hours | 200 with the original response body and the header Idempotent-Replayed: true. TokenLab does not run or charge the request again |
| The key was used in any other way, for example: you received the result, the request was streamed, the result was larger than 1 MB, or more than 24 hours passed | 409 with code idempotency_replay_unavailable |
| The body is different from the first request | 409, usually with code idempotency_conflict. Some requests return idempotency_replay_unavailable |
A 409 with either code means that TokenLab did not run the request again. A streamed request with a key cannot run twice, but TokenLab cannot send its output again.
This example retries a timed-out Chat Completions request with the same key until it gets the result:
import os
import time
import uuid
import openai
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=120.0,
max_retries=0,
)
def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
key = str(uuid.uuid4()) # Save this key with your job record.
for wait in waits:
time.sleep(wait)
try:
return client.chat.completions.create(
model=model,
messages=messages,
extra_headers={"Idempotency-Key": key},
)
except (openai.APITimeoutError, openai.APIConnectionError):
continue # No response: retry with the same key and body.
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# The first attempt can still be running. A later retry returns its result.
raise RuntimeError(f"No result for Idempotency-Key {key}")If the last attempt still returns idempotency_replay_unavailable, TokenLab cannot return that result. Send the request with a new key only if a second run and a second charge are acceptable.
Keep the Request ID
Response headers include a Request ID for tracing. Save it with the endpoint, model, time, and your own user or job ID. For async work, also save task_id and billing_transaction_id when present.
When contacting support, include those IDs and a redacted example. Never send API keys, management tokens, private media, signed URLs, or complete private prompts.