Codigos de erro

Toda resposta de erro do Tokia segue um formato previsivel. Existem dois schemas, dependendo do tipo de endpoint:

Proxy /v1/* (chamadas a modelos de IA) — formato OpenAI-compatible
REST (dashboard, billing, keys) — formato Tokia simplificado

Erros do proxy `/v1/*`

Erros das chamadas a modelos de IA seguem o formato OpenAI:

json

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Muitas requisicoes simultaneas. Aguarde alguns segundos e tente novamente.",
    "code": "rate_limit_exceeded"
  }
}

Tokia normaliza todos os erros dos provedores em categorias fixas. A mensagem e em pt-BR e sempre acionavel, nunca vaza nome do provedor ou detalhe interno.

HTTP	type / code	Quando acontece	O que fazer
400	`invalid_request`	Parametro invalido (model inexistente, max_tokens absurdo, messages malformado).	Verificar payload contra /v1/chat/completions.
401	`authentication_failed`	API key Tokia invalida, revogada, expirada, ou sem acesso ao modelo solicitado.	Recriar key em `/dashboard/keys` incluindo o modelo desejado.
402	`request_exceeds_balance`	O custo maximo estimado da requisicao (prompt + `max_tokens` + imagens) excede o saldo disponivel.	Reduza `max_tokens`, encurte o prompt, ou adicione saldo.
404	`model_not_found`	ID do modelo nao existe no catalogo Tokia. A resposta inclui `did_you_mean` com sugestoes.	Ver lista atual em /docs/models.
422	`image_input_not_bounded`	Nao conseguimos limitar o custo de imagens neste modelo.	Use um modelo de visao listado no catalogo ou envie so texto.
429	`rate_limit_exceeded`	Throttling Tokia (default 100 req/min/IP) ou limite do modelo.	Backoff exponencial, esperar 1-2s e retentar. Le header `retry-after`.
429	`api_key_rate_limited`	Limite por API key (default 120 req/min) atingido.	Crie 2a API key em `/dashboard/keys` para paralelizar carga, ou backoff lendo `x-ratelimit-reset`.
403	`ip_blocked_by_allowlist`	IP do cliente nao esta na allowlist desta key.	Adicionar IP em `/dashboard/keys` - editar key - IP allowlist.
502	`upstream_error`	Falha temporaria na infraestrutura Tokia ou no provedor de IA.	Retentar em alguns segundos. Se persistir, contatar suporte.
503	`service_unavailable`	Modelo temporariamente indisponivel (manutencao, recarga em curso).	Retentar em alguns minutos. Tokia ja foi notificada automaticamente.
503	`cost_guard_unavailable`	Nao conseguimos confirmar o custo maximo da requisicao (saldo, cambio ou tabela de precos indisponiveis). Por seguranca, a requisicao nao e enviada ao provedor.	Retentar em instantes. Se persistir, contatar suporte.
503	`model_without_price`	O modelo ainda nao tem preco publicado no gateway; a Tokia nao envia requisicoes cujo custo nao consegue calcular.	Escolher outro modelo ou contatar suporte.

Erros REST (dashboard / billing / keys)

Endpoints REST da API Tokia (/api-keys, /topups, /payment-methods, /me/profile etc.) usam formato simplificado:

json

{
  "error": "cpf_required",
  "details": "Preencha CPF/CNPJ no profile antes de fazer top-up."
}

Codigos HTTP seguem convencao REST. Abaixo, os codigos de erro mais comuns por status HTTP.

400 Bad Request

Codigo	Significado
`cpf_required`	Profile sem CPF/CNPJ. Cliente precisa preencher em `PUT /me/profile` antes de fazer top-up ou cadastrar cartao.
`invalid_cpf_cnpj_format`	Formato invalido (nao tem 11 ou 14 digitos).
`invalid_cpf_cnpj_checksum`	Digitos verificadores nao batem.
`amount must be number between 20 and 5000`	Valor de top-up fora do intervalo. Minimo R$ 20, maximo R$ 5.000.
`name must be 3-50 chars`	Nome de API key invalido.
`no_valid_models`	Lista `model_ids[]` passada nao tem nenhum ID valido do catalogo.
`card_rejected`	O processador de pagamentos rejeitou o cartao (recusado, expirado, dados incorretos).
`missing_card_or_holder_info`	POST `/payment-methods` sem campos obrigatorios.

401 Unauthorized

Codigo	Significado
(sem corpo)	Token Bearer ausente ou invalido. Verifique header `Authorization`.
`invalid_token`	Webhook do processador de pagamentos com token errado (nao afeta clientes).
`invalid_signature`	Webhook de autenticacao com HMAC invalido (nao afeta clientes).

402 Payment Required

Codigo	Significado
`request_exceeds_balance`	Saldo insuficiente para cobrir o custo maximo estimado. Veja como o saldo funciona.

403 Forbidden

Codigo	Significado
`forbidden`	Endpoint admin sem permissao. Cliente normal ve 403; admins precisam estar na allowlist.
`key_model_access_denied`	API key nao tem o modelo solicitado em sua lista permitida. Crie nova key incluindo o modelo.

404 Not Found

Codigo	Significado
`key_not_found`	DELETE `/api-keys/:id` com id que nao pertence ao user.
`payment_method_not_found`	DELETE `/payment-methods/:id` com id invalido.
`profile_not_found`	GET `/me/profile` antes do profile ser criado no primeiro login.

500 Internal Server Error

Erro inesperado Tokia. Reporte para contato@usetokia.com com timestamp + request_id (do header x-tokia-request-id da response).

Headers uteis

Toda resposta de /v1/* retorna headers extras para debug e controle de fluxo:

Header	Quando aparece	Para que serve
`x-tokia-request-id`	Toda resposta	UUID unico da chamada. Inclua em suporte. Cliente pode enviar o proprio header para correlacao ponta-a-ponta.
`x-tokia-max-tokens-applied`	Quando `max_tokens` e omitido	Mostra o valor de `max_tokens` que o Tokia aplicou automaticamente (default 4.096).
`x-ratelimit-limit`	Toda resposta	Quantos requests por minuto a key pode fazer.
`x-ratelimit-remaining`	Toda resposta	Quantos requests ainda cabem na janela atual.
`x-ratelimit-reset`	Toda resposta	Unix timestamp (segundos) quando o contador zera.
`retry-after`	So em 429	Segundos ate poder retentar.

Padrao de retry recomendado

Para erros retentaveis (429 e 5xx), use backoff exponencial com jitter. Exemplo em TypeScript:

async function retryableFetch(url: string, opts: RequestInit, max = 5) {
  for (let attempt = 0; attempt < max; attempt++) {
    const r = await fetch(url, opts);
    if (r.status === 429 || r.status >= 500) {
      const retryAfter = Number(r.headers.get("retry-after")) || 1;
      const wait = retryAfter * 1000 * Math.pow(2, attempt);
      const jitter = Math.random() * 500;
      await new Promise((ok) => setTimeout(ok, Math.min(wait + jitter, 30_000)));
      continue;
    }
    return r;
  }
  throw new Error("Tokia: max retries exceeded");
}

Erros 400, 401, 402, 403, 404 e 422 sao definitivos — retentar sem corrigir o request nao vai ajudar.