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

StatusSignificadoAção típica
400Um campo, ID de modelo ou entrada é inválidoCorrija a requisição; não a repita sem alterações
401API key ausente, inválida, expirada ou revogadaSubstitua a chave
402Saldo ou limite da API key muito baixoRecarregue, aumente o limite ou reduza a requisição
403Esta chave não pode usar o recurso ou modelo, ou a conta está restritaAltere as permissões ou o modelo da chave, ou entre em contato com o suporte
404O recurso não existe ou não está mais disponívelVerifique o ID e a API key que o criou
409A 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 novamenteUse 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
413A requisição ou o arquivo enviado é muito grandeReduza a entrada para o limite documentado do modelo ou endpoint
429Limite de requisições atingidoAguarde pelo Retry-After
500–504Serviço indisponível ou falha de redeTente novamente apenas quando retryable for true; respeite o retry_after e limite as tentativas

Códigos de erro comuns

CódigoO que significaO que alterar
invalid_api_keyA API key está ausente, inválida, inativa ou revogadaVerifique o cabeçalho Authorization e o valor da chave
expired_api_keyA chave expirouCrie ou selecione uma chave ativa
insufficient_balanceO saldo da conta não cobre a requisiçãoAdicione fundos, reduza a requisição ou escolha um modelo de menor custo
quota_exceededA API key atingiu seu próprio limiteAumente o limite da chave ou use uma chave autorizada diferente
model_not_allowedA chave não pode usar o modelo solicitadoAtualize a lista de modelos da chave ou escolha um modelo permitido
user_suspended, account_restrictedHTTP 403. A conta não pode usar a APIEntre em contato com o suporte com o Request ID
invalid_delivery_policyHTTP 400. O cabeçalho X-TokenLab-Delivery-Policy não é auto, verified ou officialEnvie um dos três valores ou remova o cabeçalho
model_not_foundO ID do modelo é desconhecido ou indisponívelLeia /v1/models e use um ID de modelo atual
context_length_exceededA entrada é maior do que o modelo aceitaRemova o histórico ou escolha um modelo com uma janela de contexto maior
missing_required_parameterUm campo obrigatório está ausente. param o nomeia, por exemplo model em requisições de áudio e imagem, que não possuem modelo padrãoEnvie o campo que param nomeia
invalid_valueUm campo tem um valor que o modelo não aceita, por exemplo um valor de reasoning_effort. A mensagem lista os valores aceitosUse um dos valores listados
invalid_response_format_typeHTTP 400. response_format é um objeto sem um type utilizável, ou com um type que este endpoint não aceita. param é response_formatDefina 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_urlA 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 campoEnvie uma URL de imagem HTTPS pública ou um URI de dados suportado
unsupported_model_capabilityNenhuma 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 suportadosRemova ou altere o parâmetro, ou escolha outro nível de Delivery ou modelo; não repita a requisição sem alterações
unpriceable_selectionA 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 seletorDefina o campo que param nomeia
model_pricing_unavailableHTTP 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 é falseNã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_conflictHTTP 409. A Idempotency-Key pertence a uma requisição diferente. A TokenLab não executou esta requisiçãoEnvie uma nova requisição com uma nova chave
idempotency_replay_unavailableHTTP 409. A Idempotency-Key já foi usada e a TokenLab não tem resultado para retornar. A TokenLab não executou esta requisição novamenteSe 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_replayableHTTP 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 novamenteNão repita a requisição com esta chave. Envie uma nova chave apenas se desejar uma nova tarefa
rate_limit_exceededMuitas requisições foram enviadas na janela atualAguarde pelo Retry-After
all_channels_failedO modelo selecionado não pode atender a esta requisiçãoTente novamente apenas quando retryable for true; respeite o retry_after e limite as tentativas
timeout_errorA requisição não terminou a tempoTente 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

ErroRepetir a mesma requisição?
400, 401, 402, 403, 404, 413Não. Altere a requisição, credenciais, saldo, permissões ou entrada.
429Sim, após o atraso fornecido pelo servidor.
500–504Tente novamente apenas quando retryable for true; respeite o retry_after e limite as tentativas
Conexão fechada antes de qualquer respostaSim, 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ídaNã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 com 400.
  • 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-Key e o mesmo corpo.
  • Após qualquer resposta que não seja 409 com idempotency_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/generations e POST /v1/worlds/generations
  • POST /v1/images/generations e POST /v1/images/edits quando retornam uma tarefa
  • POST /v1/responses com "background": true
  • POST /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çãoResultado
A primeira requisição ainda está em execução409 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 horas200 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 passaram409 com o código idempotency_replay_unavailable
O corpo é diferente da primeira requisição409, 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.

De uma requisição a uma investigação e suporte

Nesta página