Resolução de problemas da API: erros comuns
Todo endpoint na referência está marcado como Planned hoje: é o contrato publicado e ainda não responde. Esta página lista os erros que a API retornará, para que seu código possa tratá-los desde o primeiro dia.
Leia o erro primeiro #
Todo erro responde com um status 4xx ou 5xx com o mesmo corpo:
{ "error": { "code": "forbidden", "message": "…" } }message é uma frase em inglês simples que explica o que deu errado. Registre-a, mas faça ramificações no seu código com base em code, nunca em message.
401 unauthorized #
A API não aceitou seu token. Verifique, nesta ordem:
- O cabeçalho está exatamente como
Authorization: Bearer <token>, com a palavraBearere um espaço. - O token foi copiado por completo. Ele é mostrado apenas uma vez, quando você o cria.
- O token ainda está ativo. Em Users › API & MCP, a tabela Access tokens mostra a validade e o status de cada token, e Show revoked tokens lista os antigos.
- Se expirou ou foi revogado, crie um novo (ou Rotate ele) e atualize sua variável de ambiente.
403 forbidden #
O token é válido, mas não tem a permissão que o endpoint precisa. Cada endpoint na referência lista sua permissão, como can_fan_read ou can_sales_read.
- Encontre a permissão na coluna Permission do endpoint.
- Em Users › API & MCP, clique em Edit no token e marque a permissão.
- Chame
GET /v1/workspace: a resposta lista o que o token pode fazer.
Um 403 também ocorre quando um token que não é de owner envia o cabeçalho LanaChat-Workspace. Remova-o.
429 rate_limited #
Cada token pode enviar 600 requisições por minuto. Toda resposta traz RateLimit-Remaining e RateLimit-Reset.
- Espere o número de segundos indicado em
Retry-Aftere tente novamente. - Navegue por listas com
limit=100em vez de uma chamada por item. - Enviar mensagens para fans também está sujeito aos limites do próprio Telegram: veja Telegram accounts and pools.
Os outros códigos #
| Status | code | O que fazer |
|---|---|---|
| 400 | invalid_request | Um campo está faltando ou no formato errado: message indica qual |
| 402 | insufficient_balance | Recarregue antes de comprar |
| 404 | not_found | O id não existe neste workspace: verifique se está usando o token correto |
| 409 | conflict | A alteração viola uma regra, ou uma Idempotency-Key foi reutilizada com corpo diferente |
| 500 | server_error | Tente novamente depois com a mesma Idempotency-Key |
Envie uma Idempotency-Key em todo POST: assim, uma nova tentativa nunca executa o trabalho duas vezes. O helper em the quick start já tenta novamente 429 e 5xx para você.
Webhooks que falham #
Uma entrega conta como falha quando seu servidor não responde com 2xx em até 10 segundos.
- Responda rápido. Retorne
2xximediatamente, depois faça o trabalho lento em segundo plano. - Cheque a assinatura no corpo bruto, antes de qualquer parsing JSON. Um corpo parseado e re-serializado nunca bate.
- Cheque o relógio do seu servidor. Um timestamp com mais de 5 minutos é recusado pelo código de exemplo, então um relógio fora de sincronia rejeita todas as entregas.
- Aceite ambos os valores
v1durante uma rotação de segredo. - Teste com
POST /webhooks/{id}/test(Planned), que envia umping, e reenvie uma entrega com/deliveries/{delivery_id}/retry(Planned) depois de corrigir seu lado.
Entregas falhas são tentadas 8 vezes em cerca de 24 horas. Após 3 dias de falhas o endpoint é pausado; reative com PATCH /webhooks/{id} (Planned). O mesmo evento pode chegar duas vezes: ignore duplicatas pelo id. Veja Webhooks.
Ainda com problemas? #
Abra a ajuda no balão no canto inferior direito do Console e escreva para a equipe com o endpoint, o status, o code e o horário da chamada. Nunca cole o token em si. Veja Get help.