Troubleshooting

Lista de erros comuns e como resolver. Se não está aqui, escreve pra suporte@usetokia.com.br 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.

Tokia tem 100 req/min/IP default. Modelos gratuitos também têm rate limit (~20 req/min compartilhado).

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"	Provedor de IA temporariamente indisponível 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 `chat`agora 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.

Sintoma	Causa	Solução
`cpf_required` em POST /topups	Profile sem CPF/CNPJ (LGPD + emissão de nota fiscal)	Preencha CPF em /dashboard antes do primeiro top-up.
pix pago mas saldo não apareceu	Confirmação do pagamento 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`	O processador de pagamentos recusou (cartão inválido, expirado, dados errados)	Confira dados ou tente outro cartão. O motivo exato não é revelado.

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	Clique em Sair no dashboard e faça login de novo.
Login Google trava em loop	Cookie de terceiros bloqueado (Chrome strict mode)	Habilite cookies de terceiros pra `usetokia.com`.

Sintoma	Causa	Solução
Chamada IA OK mas saldo não diminuiu	A reconciliação automática ainda não rodou (≤ 60s) OU modelo gratuito (custo R$ 0)	Aguarde 60s. Veja em `/dashboard/usage` se evento foi reconciliado.
Custo cobrado parece alto	Cada modelo tem um preço diferente, em reais	Veja /docs/pricing pra calculadora e o preço por modelo. O Tokia Free Test custa zero.