# Códigos de erro

> Referência de tratamento de erros da API do TBit

- Página: https://tbit.app/pt/docs/api/errors
- URL base: `https://rest-api.tbit.app/v1`
- Autenticação: cabeçalho `X-API-Key` com a sua chave em cada requisição (os exemplos a leem da variável de ambiente `TBIT_API_KEY`)

Quer saber por que uma mensagem de WhatsApp não foi entregue? Veja [Erros de entrega no WhatsApp (em espanhol)](https://tbit.app/es/docs/errores-de-entrega-whatsapp).

## Formato da resposta de erro

Todos os erros seguem uma estrutura JSON consistente:

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Activity not found"
  }
}
```

## Códigos de erro

| Status | Código | Descrição |
| --- | --- | --- |
| `400` | `VALIDATION_ERROR` | Body da requisição ou parâmetros de consulta inválidos |
| `401` | `UNAUTHORIZED` | Chave de API ausente ou inválida |
| `404` | `NOT_FOUND` | Recurso não encontrado ou não pertence ao seu agente |
| `405` | `METHOD_NOT_ALLOWED` | Método HTTP não suportado neste endpoint |
| `409` | `CONFLICT` | O recurso já existe (ex.: contato com este canal) |
| `422` | `SEND_FAILED` | Falha no envio do modelo (ex.: sem janela de mensagens) |
| `429` | `RATE_LIMITED` | Limite de taxa excedido (100 requisições/minuto) |
| `500` | `INTERNAL_ERROR` | Erro inesperado do servidor |

## Headers de limite de taxa

Toda resposta inclui nos headers a informação do limite de taxa:

| Header | Descrição |
| --- | --- |
| `X-RateLimit-Remaining` | Requisições restantes na janela atual |
| `X-RateLimit-Reset` | Timestamp (ms) em que a janela é reiniciada |

## Tratamento de erros

Boas práticas para tratar erros da API:

- Sempre verifique o código de status HTTP antes de interpretar o corpo da resposta
- Implemente backoff exponencial para erros 429 (limite de taxa)
- Registre os códigos e as mensagens de erro para depuração
- Não repita erros 400 ou 401: corrija a requisição primeiro