Errors agents can act on

OpenAI-compatible TokenLab errors can include structured hints for an agent or application. Use these fields when present; do not parse the human-readable message to decide what to do. Anthropic Messages and Gemini APIs keep their native error formats, so the extensions on this page apply only to OpenAI-compatible Chat Completions and Responses errors.

Optional error fields

All fields below appear inside the error object and may be absent.

Field	Type	Use
`did_you_mean`	`string`	Closest available model ID
`suggestions`	`array`	Models that may fit the request
`alternatives`	`array`	Models currently available as alternatives
`hint`	`string`	A short explanation or suggested action
`retryable`	`boolean`	Whether the same request may succeed later
`retry_after`	`number`	Seconds to wait before trying again
`balance_usd`	`number`	Current balance in USD
`estimated_cost_usd`	`number`	Estimated cost of the rejected request

Your client should still handle every error by its HTTP status and code. Treat these extra fields as useful context, not required fields.

Unknown model

A misspelled or unavailable model returns 400 model_not_found. If did_you_mean is present, show it to the user or retry only when your product already has permission to change the selected model.

{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.6-terra",
    "suggestions": [
      {"id": "gpt-5.6-terra"},
      {"id": "gpt-5.6-luna"}
    ],
    "hint": "Did you mean 'gpt-5.6-terra'? Use GET https://api.tokenlab.sh/v1/models to list all available models."
  }
}

Insufficient balance

402 insufficient_balance can include the current balance and the estimated amount required. Your application can offer a top-up link, a less expensive model, or a smaller request.

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5.6-luna"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

Temporarily unavailable

A 503 all_channels_failed response means the requested model is temporarily unavailable. Respect retry_after when retryable is true, or let the user choose an item from alternatives.

{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-5", "status": "available", "tags": []},
      {"id": "gpt-5.6-luna", "status": "available", "tags": []}
    ],
    "hint": "Retry in 30s or try an alternative model."
  }
}

Rate limit

For 429 rate_limit_exceeded, wait for retry_after seconds or use the standard Retry-After response header.

{
  "error": {
    "message": "Rate limit: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Retry after 8s."
  }
}

Context too long

400 context_length_exceeded is not fixed by sending the same request again. Shorten the input or let the user choose a model with a larger context window.

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-5"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

Find the right API format

Read tokenlab.accepted_request_formats from GET /v1/models/{model} before using a model-specific API.

Value	Endpoint
`chat_completions`	`/v1/chat/completions`
`responses`	`/v1/responses`
`messages`	`/v1/messages`
`gemini`	`/v1beta/models/{model}:generateContent`

An accepted format confirms the endpoint. Individual tools and fields can still vary by model; check the model page before depending on them.

Find a model by task

The Models API can return a current shortlist for non-chat tasks:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Valid recommended_for values are image, video, music, 3d, tts, stt, embedding, rerank, and translation. Send the chosen model ID explicitly in the create request. TokenLab does not silently replace it with a different model.

Machine-readable overview

Agents can read a compact API overview at:

GET https://api.tokenlab.sh/llms.txt

It includes a first request, common endpoints, model filters, and error-handling guidance.

Safe retry example

This example corrects a model name only when the API returns did_you_mean. Add user confirmation if changing models can alter quality, price, or data handling in your product.

from openai import OpenAI, BadRequestError

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.tokenlab.sh/v1"
)

def chat(messages, model):
    try:
        return client.chat.completions.create(model=model, messages=messages)
    except BadRequestError as exc:
        error = exc.body.get("error", {}) if isinstance(exc.body, dict) else {}
        suggested = error.get("did_you_mean")
        if error.get("code") == "model_not_found" and suggested:
            return client.chat.completions.create(
                model=suggested,
                messages=messages,
            )
        raise

Getting Started

Core Guides

Media Guides

Errors agents can act on

Optional error fields

Unknown model

Insufficient balance

Temporarily unavailable

Rate limit

Context too long

Find the right API format

Find a model by task

Machine-readable overview

Safe retry example

​Optional error fields

​Unknown model

​Insufficient balance

​Temporarily unavailable

​Rate limit

​Context too long

​Find the right API format

​Find a model by task

​Machine-readable overview

​Safe retry example

Optional error fields

Unknown model

Insufficient balance

Temporarily unavailable

Rate limit

Context too long

Find the right API format

Find a model by task

Machine-readable overview

Safe retry example