Guias principais

Erros nos quais agentes podem atuar

Use códigos de erro, tempo de nova tentativa e sugestões de modelo sem analisar textos

Esta página descreve erros de API pública legíveis por máquina para aplicações e agentes de codificação. Ela não concede acesso a investigações de solicitações de workspace ou suporte. Para uma solicitação em seu workspace, comece com solução de problemas de solicitação.

Os erros do TokenLab compatíveis com OpenAI podem incluir dicas estruturadas para um agente ou aplicação. Use esses campos quando presentes; não analise a message legível por humanos para decidir o que fazer.

As APIs Anthropic Messages e Gemini mantêm seus formatos de erro nativos, portanto, as extensões nesta página aplicam-se apenas a erros de Chat Completions e Responses compatíveis com OpenAI.

Campos de erro opcionais

Todos os campos abaixo aparecem dentro do objeto error e podem estar ausentes.

CampoTipoUso
did_you_meanstringSubstituição para um modelo descontinuado, ou o ID de modelo disponível mais próximo
suggestionsarrayModelos que podem atender à solicitação
hintstringUma breve explicação ou ação sugerida
retryablebooleanSe a mesma solicitação pode ter sucesso posteriormente
retry_afternumberSegundos para aguardar antes de tentar novamente
balance_usdnumberSaldo atual em USD
estimated_cost_usdnumberCusto estimado da solicitação rejeitada
top_up_urlstringLink da página de faturamento, em alguns erros de insufficient_balance
min_top_up_usdnumberRecarga mínima em USD, em alguns erros de insufficient_balance

Seu cliente ainda deve lidar com cada erro pelo seu status HTTP e code. Trate esses campos extras como contexto útil, não como campos obrigatórios.

Modelo desconhecido

Um modelo com erro de digitação ou indisponível retorna 400 model_not_found. Se did_you_mean estiver presente, mostre-o ao usuário ou tente novamente apenas quando seu produto já tiver permissão para alterar o modelo selecionado.

{
  "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 /v1/models to list all available models."
  }
}

Saldo insuficiente

402 insufficient_balance pode incluir o saldo atual e o valor estimado necessário, ou um link de recarga e o valor mínimo de recarga. Sua aplicação pode oferecer um link de recarga, um modelo menos caro ou uma solicitação menor.

{
  "error": {
    "message": "Insufficient balance: this request needs about $0.35 for claude-sonnet-4-6, and your balance is $0.12. Add at least $5 to continue: https://tokenlab.sh/dashboard/billing · Why: https://tokenlab.sh/docs/en/quickstart#why-402 After you top up, your current API key works immediately, no new key needed.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "retryable": false,
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5.6-luna"},
      {"id": "deepseek-v4.1-flash"}
    ],
    "hint": "Insufficient balance: need ~$0.350000 for claude-sonnet-4-6, but balance is $0.120000. Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

Modelo indisponível

Um 503 all_channels_failed ou 503 delivery_tier_unavailable nem sempre significa uma interrupção temporária. Se a operação solicitada não tiver oferta no nível de Delivery selecionado, retryable é false e retry_after é omitido. Não repita a mesma solicitação. Verifique a disponibilidade da operação e do Delivery com GET /v1/models antes de selecionar outro modelo. Nomes semelhantes não provam disponibilidade; alternativas não verificadas são omitidas.

{
  "error": {
    "message": "This model is unavailable for the requested operation and Delivery tier.",
    "type": "all_channels_failed",
    "code": "all_channels_failed",
    "retryable": false,
    "hint": "Check the model's operation and Delivery availability with GET /v1/models. Repeating the same request will not resolve this."
  }
}

Limite de taxa

Para 429 rate_limit_exceeded, aguarde retry_after segundos ou use o cabeçalho de resposta padrão Retry-After.

{
  "error": {
    "message": "Rate limit exceeded (1000/min for user role). Please retry later.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
  }
}

Contexto muito longo

400 context_length_exceeded não é corrigido enviando a mesma solicitação novamente. Encurte a entrada ou deixe o usuário escolher um modelo com uma janela de contexto maior.

{
  "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."
  }
}

Encontre o formato de API correto

Leia tokenlab.accepted_request_formats de GET /v1/models/{model} antes de usar uma API específica de modelo.

ValorEndpoint
openai_chat_completions/v1/chat/completions
openai_responses/v1/responses
anthropic_messages/v1/messages
gemini_generate_content/v1beta/models/{model}:generateContent

Um formato aceito confirma o endpoint. Ferramentas e campos individuais ainda podem variar de acordo com o modelo; verifique a página do modelo antes de depender deles.

Encontre um modelo por tarefa

A API de Models pode retornar uma lista atual para tarefas que não são de chat:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image"

Valores válidos para recommended_for são image, video, music, 3d, tts, stt, embedding, rerank, translation e decision. Envie o ID do modelo escolhido explicitamente na solicitação de criação. O TokenLab não o substitui silenciosamente por um modelo diferente.

Visão geral legível por máquina

Agentes podem ler uma visão geral compacta da API em:

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

Ela inclui uma primeira solicitação, endpoints comuns, filtros de modelo e orientações de tratamento de erros.

Lide com um erro sem repetir a solicitação

Este exemplo faz uma solicitação, preserva o modelo selecionado e relata informações de recuperação estruturadas. As tentativas automáticas do SDK são desativadas para que sua aplicação possa decidir se uma nova tentativa é segura. Apresente sugestões de modelo para uma escolha explícita; não repita automaticamente uma geração aceita ou que excedeu o tempo limite. Para repetir uma solicitação que excedeu o tempo limite com segurança, envie-a com uma Idempotency-Key, conforme mostrado em Tente novamente com segurança com uma chave de idempotência.

import os
from openai import OpenAI, APIStatusError

with OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
) as client:
    try:
        response = client.chat.completions.create(
            model="gpt-5.6-terra",
            messages=[{"role": "user", "content": "Reply only with OK."}],
        )
        print(response.choices[0].message.content)
    except APIStatusError as exc:
        body = exc.body if isinstance(exc.body, dict) else {}
        error = body.get("error", body)
        if not isinstance(error, dict):
            error = {}
        print({
            "status": exc.status_code,
            "request_id": exc.request_id,
            "code": error.get("code"),
            "hint": error.get("hint"),
            "suggested_model": error.get("did_you_mean"),
            "retry_after": exc.response.headers.get("Retry-After") or error.get("retry_after"),
        })
        raise

Nesta página