Erros nos quais agentes podem atuar

Esta página descreve erros da API pública legíveis por aplicações e agentes de programação. Não concede acesso a investigações do workspace nem ao suporte. Para suas solicitações, consulte a solução de problemas.

Os erros da TokenLab compatíveis com OpenAI podem incluir dicas estruturadas para um agente ou aplicação. Use esses campos quando estiverem 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 opcionaisCopy Anchor Link

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

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 desconhecidoCopy Anchor Link

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 https://api.tokenlab.sh/v1/models to list all available models."
  }
}

Saldo insuficienteCopy Anchor Link

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

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

Modelo indisponívelCopy Anchor Link

503 all_channels_failed ou 503 delivery_tier_unavailable nem sempre indica uma falha temporária. Se não houver oferta para a operação no nível Delivery selecionado, retryable será false e retry_after será omitido. Não repita a mesma requisição. Confira a disponibilidade da operação e do Delivery com GET /v1/models antes de escolher outro modelo. Nomes parecidos não comprovam 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 (Rate limit)Copy Anchor Link

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

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

Contexto muito longoCopy Anchor Link

O erro 400 context_length_exceeded não é corrigido enviando a mesma solicitação novamente. Reduza 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 corretoCopy Anchor Link

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

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 tarefaCopy Anchor Link

A API de modelos (Models API) pode retornar uma lista atual de recomendações para tarefas que não sejam de chat:

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

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

Visão geral legível por máquinaCopy Anchor Link

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.

Tratar um erro sem reenviar a solicitaçãoCopy Anchor Link

O exemplo envia uma única solicitação, mantém o modelo escolhido e apresenta informações estruturadas do erro. As tentativas automáticas do SDK estão desativadas. Peça uma escolha explícita diante de sugestões de modelos; não reenvie automaticamente gerações aceitas ou que excederam o tempo limite.

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