# Resolução de problemas da API: erros comuns

_API · Leitura de 4 min · Atualizado 2026-10-23 · https://lanachat.ai/guides/pt/api-troubleshooting/_

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:

```json
{ "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:

1. O cabeçalho está exatamente como `Authorization: Bearer <token>`, com a palavra `Bearer` e um espaço.
2. O token foi copiado por completo. Ele é mostrado apenas uma vez, quando você o cria.
3. 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.
4. 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`.

1. Encontre a permissão na coluna **Permission** do endpoint.
2. Em **Users › API & MCP**, clique em **Edit** no token e marque a permissão.
3. 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-After` e tente novamente.
- Navegue por listas com `limit=100` em 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](https://lanachat.ai/guides/pt/api-telegram-accounts/).

## 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](https://lanachat.ai/guides/pt/api-overview/) 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.

1. **Responda rápido.** Retorne `2xx` imediatamente, depois faça o trabalho lento em segundo plano.
2. **Cheque a assinatura no corpo bruto**, antes de qualquer parsing JSON. Um corpo parseado e re-serializado nunca bate.
3. **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.
4. **Aceite ambos os valores `v1`** durante uma rotação de segredo.
5. **Teste** com `POST /webhooks/{id}/test` (Planned), que envia um `ping`, 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](https://lanachat.ai/guides/pt/api-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](https://lanachat.ai/guides/pt/get-help/).

## Artigos relacionados

- [API LanaChat: início rápido, autenticação e erros](https://lanachat.ai/guides/pt/api-overview/)
- [API: webhooks, eventos e assinaturas](https://lanachat.ai/guides/pt/api-webhooks/)
- [API: membros da equipe, funções e tokens de acesso](https://lanachat.ai/guides/pt/api-team/)
- [Receitas rápidas da API: copiar, colar, executar](https://lanachat.ai/guides/pt/api-recipes/)