Troubleshooting
Lista de erros comuns e como resolver. Se não está aqui, escreve pra contato@usetokia.com com o x-request-id da response.
Autenticação · 401 / 403
| Sintoma | Causa provável | Solução |
|---|
401 em qualquer endpoint | Header Authorization ausente, malformado ou key revogada | Confira: Authorization: Bearer sk-tokia-... (com "Bearer " antes). Em /dashboard/keys, valide se a key está ativa. |
authentication_failed em /v1/chat/completions | Key não tem o modelo solicitado na lista permitida | Edite a key incluindo o modelo (botão "Editar" em /dashboard/keys) OU crie nova key com todos os modelos. |
403 em /admin/* | User não tem role admin (esperado pra cliente normal) | Endpoints /admin/* são privados. Use os endpoints de cliente. |
Rate limit · 429
Tokia tem 100 req/min/IP default. Modelos free upstream também têm rate limit (~20 req/min compartilhado).
✓Implemente backoff exponencial: ao receber 429, aguarde 1s, 2s, 4s, 8s, 16s. Maioria dos SDKs OpenAI (Python, Node) faz isso automaticamente com max_retries.
Modelo · 404 / 503
| Sintoma | Causa | Solução |
|---|
model_not_found (404) | ID do modelo digitado errado | Confira lista em /docs/models. IDs são case-sensitive (ex: openrouter/openai/gpt-4o-mini). |
service_unavailable (503) com "Serviço temporariamente indisponível" | Provider upstream sem créditos OU em manutenção | Tokia já foi notificada. Retente em 5-15 min. Status atualizado em /status. |
GET /models?category=chat retorna lista vazia | Alias chat apontava pra categoria interna inexistente. Corrigido em 2026-05-18 (a categoria real é llm; o alias chatagora resolve pra ela). | Atualize sua versão do SDK ou troque a query por ?category=llm. Ambos retornam o mesmo conjunto após o fix. |
Pagamento · top-up
| Sintoma | Causa | Solução |
|---|
cpf_required em POST /topups | Profile sem CPF/CNPJ (LGPD + Asaas) | Preencha CPF em /dashboard antes do primeiro top-up. |
| PIX pago mas saldo não apareceu | Webhook Asaas atrasou (raro) OU pagamento ainda em pending | Aguarde 60s e atualize /dashboard. Persiste > 5min? Mande email com print do PIX. |
card_rejected em /payment-methods | Asaas recusou (cartão inválido, expirado, dados errados) | Confira dados ou tente outro cartão. Asaas não revela motivo exato. |
Dashboard · Next.js
| Sintoma | Causa | Solução |
|---|
| "Não foi possível carregar dados da API: fetch failed" | Backend Tokia momentaneamente indisponível | Confira /status. Recarregue (Ctrl+Shift+R) em 30s. |
| "Cookies can only be modified in a Server Action or Route Handler" | Sessão expirada ou cookie corrompido | Faça logout em /api/logto/sign-out e login de novo. |
| Login Google trava em loop | Cookie de terceiros bloqueado (Chrome strict mode) | Habilite cookies de terceiros pra auth.toolpad.cloud. |
Custos · debit demora
| Sintoma | Causa | Solução |
|---|
| Chamada IA OK mas saldo não diminuiu | Cron reconcile_spend ainda não rodou (≤ 60s) OU modelo free (markup 1.0x, custo R$ 0) | Aguarde 60s. Veja em /dashboard/usage se evento foi reconciliado. |
| Custo cobrado parece alto | Markup decrescente (DR-009) — modelo barato tem markup alto | Veja /docs/pricing pra calculadora + tabela de markup. gpt-4o-mini = 2x; modelos free = 0 custo. |
Não está aqui?
Manda email pra contato@usetokia.com com:
- O
x-request-id do header de response (se houver) - O comando ou snippet que falhou
- O response body completo
- Timestamp aproximado (com fuso BRT)