Guias principais
Lidar com erros da API
Leia códigos de erro, tente novamente apenas quando útil e mantenha o Request ID
Lide com erros através do status HTTP e do code. A message é escrita para humanos e pode mudar sem aviso prévio.
Chat Completions e Responses usam um objeto error no estilo OpenAI. Anthropic Messages e Gemini mantêm seus próprios formatos de erro, portanto, não use um único parser para toda a API TokenLab.
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}Apenas message e type estão sempre presentes em erros compatíveis com OpenAI criados pelo TokenLab. Outros campos aparecem quando são relevantes.
Códigos de status
| Status | Significado | Ação típica |
|---|---|---|
400 | Um campo, ID de modelo ou entrada é inválido | Corrija a requisição; não a repita sem alterações |
401 | API key ausente, inválida, expirada ou revogada | Substitua a chave |
402 | Saldo ou limite da API-key muito baixo | Recarregue, aumente o limite ou reduza a requisição |
403 | Esta chave não pode usar o recurso ou modelo | Altere as permissões da chave ou o modelo |
404 | O recurso não existe ou não está mais disponível | Verifique o ID e a API key que o criou |
413 | A requisição ou arquivo enviado é muito grande | Reduza a entrada para o limite documentado do modelo ou endpoint |
429 | Limite de requisições atingido | Aguarde pelo Retry-After |
500–504 | Serviço indisponível ou falha de rede | Tente novamente apenas com retryable: true; respeite retry_after e limite as tentativas |
Códigos de erro comuns
| Código | O que significa | O que alterar |
|---|---|---|
invalid_api_key | A chave API está ausente, inválida, inativa ou revogada | Verifique o cabeçalho Authorization e o valor da chave |
expired_api_key | A chave API expirou | Crie ou selecione uma chave ativa |
insufficient_balance | O saldo da conta não cobre a requisição | Adicione fundos, reduza a requisição ou escolha um modelo de menor custo |
quota_exceeded | A API key atingiu seu próprio limite | Aumente o limite da chave ou use uma chave autorizada diferente |
model_not_allowed | A chave não pode usar o modelo solicitado | Atualize a lista de modelos da chave ou escolha um modelo permitido |
model_not_found | O ID do modelo é desconhecido ou indisponível | Leia /v1/models e use um ID de modelo atual |
context_length_exceeded | A entrada é maior do que o modelo aceita | Remova o histórico ou escolha um modelo com uma janela de contexto maior |
rate_limit_exceeded | Muitas requisições foram enviadas na janela atual | Aguarde pelo Retry-After |
payload_too_large | O corpo da requisição ou arquivo excede o limite do endpoint | Reduza ou comprima a entrada |
all_channels_failed | O modelo selecionado não pode atender a esta requisição | Tente novamente apenas com retryable: true; respeite retry_after e limite as tentativas |
timeout_error | A requisição não terminou a tempo | Tente novamente apenas quando a operação for segura para repetir |
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.
Alguns erros compatíveis com OpenAI incluem campos opcionais como did_you_mean, suggestions, alternatives, hint, retryable ou retry_after. Veja Erros nos quais agentes podem atuar.
Quando uma solicitação foi executada por uma rota Official e o serviço upstream rejeitou a própria solicitação, por exemplo por uma entrada que não aceita ou por uma decisão de política de conteúdo, o erro também traz upstream: a message do upstream como foi informada, além de code e source (o nome do serviço upstream) quando conhecidos. Erros de Anthropic Messages e Gemini trazem o mesmo objeto dentro do seu próprio error. Continue decidindo por code e type; os valores de upstream.code são definidos pelo serviço upstream e podem mudar.
Decisões de nova tentativa (Retry)
| Erro | Repetir a mesma requisição? |
|---|---|
400, 401, 402, 403, 404, 413 | Não. Altere a requisição, credenciais, saldo, permissões ou entrada. |
429 | Sim, após o atraso fornecido pelo servidor. |
500–504 | Tente novamente apenas com retryable: true; respeite retry_after e limite as tentativas |
| Conexão fechada antes de qualquer resposta | Às vezes. Para operações de criação, verifique se uma tarefa ou efeito colateral já existe. |
| Stream interrompido após a chegada da saída | Não considere uma resposta completa. Repetir pode gerar uma saída diferente ou uma segunda cobrança. |
Para criação de imagens, vídeos, música, 3D e Worlds, salve o ID da tarefa assim que ele for retornado. Se uma requisição de criação atingir o tempo limite, verifique o registro da tarefa antes de enviar outra requisição de criação.
Mantenha o Request ID
Os cabeçalhos de resposta incluem um Request ID para rastreamento. Salve-o com o endpoint, modelo, horário e seu próprio ID de usuário ou trabalho. Para trabalho assíncrono, salve também o task_id e o billing_transaction_id quando presentes.
Ao entrar em contato com o suporte, inclua esses IDs e um exemplo redigido. Nunca envie API keys, tokens de gerenciamento, mídia privada, URLs assinadas ou prompts privados completos.