TokenLab

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

StatusMeaningTypical action
400A field, model ID, or input is invalidFix the request; do not repeat it unchanged
401API key is missing, invalid, expired, or revokedReplace the key
402Balance or API-key limit is too lowTop up, raise the limit, or reduce the request
403This key cannot use the resource or model, or the account is restrictedChange the key's permissions or model, or contact support
404Resource does not exist or is no longer availableCheck the ID and the API key that created it
409The 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 againUse a new key for a new request. To decide whether to retry with the same key, see Retry safely with an idempotency key
413Request or uploaded file is too largeReduce the input to the documented model or endpoint limit
429Request limit reachedWait for Retry-After
500–504Service unavailable or network failureRetry only when retryable is true; respect retry_after and limit attempts

Common error codes

CodeWhat it meansWhat to change
invalid_api_keyThe API key is missing, invalid, inactive, or revokedCheck the Authorization header and key value
expired_api_keyThe key has expiredCreate or select an active key
insufficient_balanceThe account balance cannot cover the requestAdd funds, reduce the request, or choose a lower-priced model
quota_exceededThe API key reached its own limitIncrease that key's limit or use a different authorized key
model_not_allowedThe key cannot use the requested modelUpdate the key's model list or choose an allowed model
user_suspended, account_restrictedHTTP 403. The account cannot use the APIContact support with the Request ID
invalid_delivery_policyHTTP 400. The X-TokenLab-Delivery-Policy header is not auto, verified, or officialSend one of the three values, or remove the header
model_not_foundThe model ID is unknown or unavailableRead /v1/models and use a current model ID
context_length_exceededInput is longer than the model acceptsRemove history or choose a model with a larger context window
missing_required_parameterA required field is missing. param names it, for example model on audio and image requests, which have no default modelSend the field that param names
invalid_valueA field has a value that the model does not accept, for example a reasoning_effort value. The message lists the accepted valuesUse one of the listed values
invalid_response_format_typeHTTP 400. response_format is an object without a usable type, or with a type this endpoint does not accept. param is response_formatSet response_format.type to text, json_object, or json_schema; with json_schema, also send json_schema.name and json_schema.schema
invalid_image_urlTokenLab 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 fieldSend a public HTTPS image URL or a supported data URI
content_policy_violationHTTP 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_failedReview the prompt and the media, then send a revised request. See Content safety rejections
unsupported_model_capabilityNo 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 valuesRemove or change the parameter, or choose another Delivery tier or model; do not repeat the request unchanged
unpriceable_selectionThe video request leaves out a selector that its price depends on, so TokenLab cannot price it. param names the selectorSet the field that param names
model_pricing_unavailableHTTP 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 falseDo not repeat the request unchanged; choose another model or operation, or contact support with the Request ID
idempotency_conflictHTTP 409. The Idempotency-Key belongs to a different request. TokenLab did not run this requestSend a new request with a new key
idempotency_replay_unavailableHTTP 409. The Idempotency-Key was already used, and TokenLab has no result to return for it. TokenLab did not run this request againIf 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_replayableHTTP 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 againDo not repeat the request with this key. Send a new key only if you want a new task
rate_limit_exceededToo many requests were sent in the current windowWait for Retry-After
all_channels_failedThe selected model cannot serve this requestRetry only when retryable is true; respect retry_after and limit attempts
timeout_errorThe request did not finish in timeRetry 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.message as 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

ErrorRepeat the same request?
400, 401, 402, 403, 404, 413No. Change the request, credentials, balance, permissions, or input.
429Yes, after the server-provided delay.
500–504Retry only when retryable is true; respect retry_after and limit attempts
Connection closed before any responseYes, 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 arrivedDo 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/batches is different: it rejects a key longer than 256 characters with 400.
  • 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 409 with idempotency_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, and POST /v1/worlds/generations
  • POST /v1/images/generations and POST /v1/images/edits when they return a task
  • POST /v1/responses with "background": true
  • POST /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:

SituationResult
The first request is still running409 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 hours200 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 passed409 with code idempotency_replay_unavailable
The body is different from the first request409, 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.

From a request to an investigation and support

On this page