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.
| Campo | Tipo | Uso |
|---|---|---|
did_you_mean | string | Substituição para um modelo descontinuado, ou o ID de modelo disponível mais próximo |
suggestions | array | Modelos que podem atender à solicitação |
hint | string | Uma breve explicação ou ação sugerida |
retryable | boolean | Se a mesma solicitação pode ter sucesso posteriormente |
retry_after | number | Segundos para aguardar antes de tentar novamente |
balance_usd | number | Saldo atual em USD |
estimated_cost_usd | number | Custo estimado da solicitação rejeitada |
top_up_url | string | Link da página de faturamento, em alguns erros de insufficient_balance |
min_top_up_usd | number | Recarga 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.
| Valor | Endpoint |
|---|---|
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.txtEla 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