API
Códigos de erro
Referência de tratamento de erros da API do TBit
# 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 primeiroQuer saber por que uma mensagem de WhatsApp não foi entregue? Veja Erros de entrega no WhatsApp (em espanhol).
Todos os erros seguem uma estrutura JSON consistente:
{
"error": {
"code": "NOT_FOUND",
"message": "Activity not found"
}
}| 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 |
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 |
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