Guias principais
Lidar com erros de API
Leia códigos de erro, tente novamente apenas quando útil e mantenha o Request ID
Lide com erros por status HTTP e 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 analisador para toda a API da 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 pela 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, ou a conta está restrita | Altere as permissões ou o modelo da chave, ou entre em contato com o suporte |
404 | O recurso não existe ou não está mais disponível | Verifique o ID e a API key que o criou |
409 | A Idempotency-Key já foi usada: com um corpo de requisição diferente (idempotency_conflict), ou para uma requisição cujo resultado a TokenLab não pode retornar (idempotency_replay_unavailable, idempotent_response_not_replayable). A TokenLab não executou a requisição novamente | Use uma nova chave para uma nova requisição. Para decidir se deve tentar novamente com a mesma chave, veja Tente novamente com segurança usando uma idempotency key |
413 | A requisição ou o 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 quando retryable for true; respeite o retry_after e limite as tentativas |
Códigos de erro comuns
| Código | O que significa | O que alterar |
|---|---|---|
invalid_api_key | A API key está ausente, inválida, inativa ou revogada | Verifique o cabeçalho Authorization e o valor da chave |
expired_api_key | A chave 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 |
user_suspended, account_restricted | HTTP 403. A conta não pode usar a API | Entre em contato com o suporte com o Request ID |
invalid_delivery_policy | HTTP 400. O cabeçalho X-TokenLab-Delivery-Policy não é auto, verified ou official | Envie um dos três valores ou remova o cabeçalho |
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 |
missing_required_parameter | Um campo obrigatório está ausente. param o nomeia, por exemplo model em requisições de áudio e imagem, que não possuem modelo padrão | Envie o campo que param nomeia |
invalid_value | Um campo tem um valor que o modelo não aceita, por exemplo um valor de reasoning_effort. A mensagem lista os valores aceitos | Use um dos valores listados |
invalid_response_format_type | HTTP 400. response_format é um objeto sem um type utilizável, ou com um type que este endpoint não aceita. param é response_format | Defina response_format.type como text, json_object ou json_schema; com json_schema, envie também json_schema.name e json_schema.schema |
invalid_image_url | A TokenLab não pode usar uma URL de imagem: não é uma URL HTTP(S) válida ou um URI de dados de imagem, ou o host da imagem não retornou a imagem. param nomeia o campo | Envie uma URL de imagem HTTPS pública ou um URI de dados suportado |
unsupported_model_capability | Nenhuma rota do nível de Delivery selecionado suporta um parâmetro de requisição, como a operação, resolution, aspect_ratio, duration, um campo de mídia de entrada, web_search_options ou max_tokens. A mensagem nomeia cada parâmetro que não correspondeu e, quando o modelo os publica, os valores suportados | Remova ou altere o parâmetro, ou escolha outro nível de Delivery ou modelo; não repita a requisição sem alterações |
unpriceable_selection | A requisição de vídeo omite um seletor do qual seu preço depende, portanto a TokenLab não pode precificá-la. param nomeia o seletor | Defina o campo que param nomeia |
model_pricing_unavailable | HTTP 503. A requisição é válida, mas a TokenLab não pode precificar esta combinação de modelo e operação nas rotas que a requisição pode usar. A requisição não foi cobrada e retryable é false | Não repita a requisição sem alterações; escolha outro modelo ou operação, ou entre em contato com o suporte com o Request ID |
idempotency_conflict | HTTP 409. A Idempotency-Key pertence a uma requisição diferente. A TokenLab não executou esta requisição | Envie uma nova requisição com uma nova chave |
idempotency_replay_unavailable | HTTP 409. A Idempotency-Key já foi usada e a TokenLab não tem resultado para retornar. A TokenLab não executou esta requisição novamente | Se a primeira requisição ainda puder estar em execução, aguarde e tente novamente com a mesma chave. Caso contrário, envie uma nova chave. Veja Tente novamente com segurança usando uma idempotency key |
idempotent_response_not_replayable | HTTP 409. A Idempotency-Key pertence a uma requisição de criação cuja tarefa já terminou, e a TokenLab não pode retornar a resposta de criação original. O nível superior do corpo da resposta inclui task_id, próximo a error. A TokenLab não executou esta requisição novamente | Não repita a requisição com esta chave. Envie uma nova chave apenas se desejar uma nova tarefa |
rate_limit_exceeded | Muitas requisições foram enviadas na janela atual | Aguarde pelo Retry-After |
all_channels_failed | O modelo selecionado não pode atender a esta requisição | Tente novamente apenas quando retryable for true; respeite o 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 |
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 requisiçã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.
Alguns erros compatíveis com OpenAI incluem campos opcionais did_you_mean, suggestions, alternatives, hint, retryable ou retry_after. Veja Erros sobre os quais os agentes podem agir.
Quando uma requisição é executada em uma rota Official e o serviço upstream rejeita a própria requisição, como uma entrada que ele não aceita ou uma decisão de política de conteúdo, o erro também carrega upstream: a message do upstream conforme relatada, mais code e source (o nome do serviço upstream) quando conhecidos. Erros de Anthropic Messages e Gemini carregam o mesmo objeto dentro de seu próprio error. Continue ramificando em code e type; os valores de upstream.code são definidos pelo serviço upstream e podem mudar.
Decisões de nova tentativa
| 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 quando retryable for true; respeite o retry_after e limite as tentativas |
| Conexão fechada antes de qualquer resposta | Sim, quando a requisição está listada em Tente novamente com segurança usando uma idempotency key e possui uma Idempotency-Key: envie-a novamente com a mesma chave e corpo. Caso contrário, verifique primeiro se uma tarefa ou efeito colateral já existe. |
| Stream interrompido após a chegada da saída | Não chame de resposta completa. Repetir pode gerar uma saída diferente ou uma segunda cobrança. |
Para criação de imagem, vídeo, música, 3D e Worlds, salve o ID da tarefa assim que ele for retornado. Se uma requisição de criação expirar (timeout), envie-a novamente com a mesma Idempotency-Key e corpo para obter a tarefa original. Sem uma chave, verifique o registro da tarefa antes de enviar outra requisição de criação.
Tente novamente com segurança usando uma idempotency key
Um timeout ou uma conexão fechada não informa se a TokenLab executou a requisição. Adicione um cabeçalho Idempotency-Key às requisições listadas abaixo. Assim, uma nova tentativa da mesma requisição não pode executá-la ou cobrá-la uma segunda vez.
- Use um novo valor único para cada operação, por exemplo, um UUID. Uma chave pode ter até 255 caracteres. A TokenLab ignora uma chave mais longa, e a requisição então não tem proteção de idempotência: uma nova tentativa é executada e cobrada novamente.
POST /v1/messages/batchesé diferente: rejeita uma chave com mais de 256 caracteres com400. - Salve a chave com seu próprio registro de trabalho antes de enviar a requisição.
- Ao tentar novamente, envie a mesma API key, a mesma
Idempotency-Keye o mesmo corpo. - Após qualquer resposta que não seja
409comidempotency_replay_unavailable, não use essa chave novamente. Envie qualquer nova tentativa com uma nova chave. - Desative as novas tentativas do SDK (
max_retries=0), para que seu código decida quando reutilizar uma chave.
Sem o cabeçalho, cada nova tentativa é uma nova requisição.
Requisições que criam uma tarefa
Estas requisições de criação aceitam Idempotency-Key:
POST /v1/videos/generations,POST /v1/music/generations,POST /v1/3d/generationsePOST /v1/worlds/generationsPOST /v1/images/generationsePOST /v1/images/editsquando retornam uma tarefaPOST /v1/responsescom"background": truePOST /v1/messages/batches
Se uma requisição de criação expirar, envie-a novamente sem alterações. A TokenLab retorna o resultado da requisição de criação original e não cria, despacha ou cobra uma segunda tarefa. Geralmente, o resultado é a tarefa original com o mesmo id (para Responses, o objeto de resposta original), e você continua a consultá-lo. Para tarefas de vídeo, música, 3D, Worlds e imagem, o resultado também pode ser o erro original quando a primeira requisição de criação falhou. Se tal tarefa já terminou e a TokenLab não tem resposta de criação armazenada, a nova tentativa retorna 409 com o código idempotent_response_not_replayable, e o nível superior do corpo da resposta inclui task_id.
Se você enviar um corpo diferente com uma chave que a TokenLab já aceitou, a TokenLab rejeita a requisição e não cria uma tarefa. Requisições de criação de vídeo, música, 3D e Worlds retornam 409 com o código idempotency_conflict. Message Batches retorna 409 com o tipo de erro conflict_error. Para tarefas de imagem e para requisições de Responses com background: true, o código de status e o código de erro para este caso não são garantidos. Não repita a requisição com a mesma chave.
Chat Completions, Responses e Messages
POST /v1/chat/completions, POST /v1/responses sem background e POST /v1/messages executam uma requisição com uma determinada chave apenas uma vez. Uma nova tentativa com a mesma chave obtém um destes resultados:
| Situação | Resultado |
|---|---|
| A primeira requisição ainda está em execução | 409 com o código idempotency_replay_unavailable |
| A primeira requisição terminou após o seu cliente desconectar. A requisição não foi transmitida (streamed), o resultado tem 1 MB ou menos, e você tenta novamente com o mesmo corpo dentro de 24 horas | 200 com o corpo da resposta original e o cabeçalho Idempotent-Replayed: true. A TokenLab não executa ou cobra a requisição novamente |
| A chave foi usada de qualquer outra forma, por exemplo: você recebeu o resultado, a requisição foi transmitida, o resultado era maior que 1 MB ou mais de 24 horas se passaram | 409 com o código idempotency_replay_unavailable |
| O corpo é diferente da primeira requisição | 409, geralmente com o código idempotency_conflict. Algumas requisições retornam idempotency_replay_unavailable |
Um 409 com qualquer um dos códigos significa que a TokenLab não executou a requisição novamente. Uma requisição transmitida com uma chave não pode ser executada duas vezes, mas a TokenLab não pode enviar sua saída novamente.
Este exemplo tenta novamente uma requisição de Chat Completions que expirou com a mesma chave até obter o resultado:
import os
import time
import uuid
import openai
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=120.0,
max_retries=0,
)
def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
key = str(uuid.uuid4()) # Save this key with your job record.
for wait in waits:
time.sleep(wait)
try:
return client.chat.completions.create(
model=model,
messages=messages,
extra_headers={"Idempotency-Key": key},
)
except (openai.APITimeoutError, openai.APIConnectionError):
continue # No response: retry with the same key and body.
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# The first attempt can still be running. A later retry returns its result.
raise RuntimeError(f"No result for Idempotency-Key {key}")Se a última tentativa ainda retornar idempotency_replay_unavailable, a TokenLab não pode retornar esse resultado. Envie a requisição com uma nova chave apenas se uma segunda execução e uma segunda cobrança forem aceitáveis.
Mantenha o Request ID
Os cabeçalhos de resposta incluem um Request ID para rastreamento. Salve-o com o endpoint, modelo, hora e seu próprio ID de usuário ou de trabalho. Para trabalho assíncrono, salve também task_id e billing_transaction_id quando presentes.
Ao entrar em contato com o suporte, inclua esses IDs e um exemplo editado. Nunca envie API keys, tokens de gerenciamento, mídia privada, URLs assinadas ou prompts privados completos.