API — Códigos de erro e troubleshooting
Referência dos códigos HTTP retornados pela API, formato dos erros (incluindo o objeto errors do 422) e causas comuns: token inválido, addon/licença, rate limit e isolamento por tenant.
API — Códigos de erro e troubleshooting
Códigos HTTP
| Código | Significado | Causa típica |
|---|---|---|
| 200 | OK | Sucesso (leitura/atualização) |
| 201 | Created | Recurso criado |
| 400 | Bad Request | Requisição inválida (ex: mensagem sem conteúdo, falha no provedor de envio) |
| 401 | Unauthenticated | Token ausente, inválido ou expirado |
| 403 | Forbidden | Sem permissão: licença sem API, addon api_access inativo, ou tenant ausente |
| 404 | Not Found | Recurso inexistente OU pertencente a outro tenant |
| 422 | Validation Error | Dados inválidos (detalhes em errors) ou regra de negócio (ex: fatura não aceita pagamento) |
| 429 | Too Many Requests | Rate limit excedido (60/min por token) |
| 500 | Server Error | Erro interno |
Formato do erro
{
"error": "Contact not found.",
"errors": { // presente apenas em 422
"name": ["O campo name é obrigatório."],
"email": ["O campo email deve ser um endereço de e-mail válido."]
}
}
Em validação (422) o Laravel retorna o objeto errors com a lista de mensagens por campo. Em demais erros, há a chave error com a descrição.

Mensagens de 403 e o que fazer
- "API access is not available on this license." — o plano do tenant não inclui API. É preciso um plano com API habilitada.
- "API Access addon is not active. Please activate it in Settings → Addons." — ative o addon
api_accessna Loja de Aplicativos. - "Tenant not found." — o usuário do token não está vinculado a um tenant.
Rate limit (429)
Limite de 60 requisições/minuto por token. A resposta inclui X-RateLimit-Limit, X-RateLimit-Remaining e, no 429, Retry-After: 60. Implemente retry com backoff e respeite o Retry-After. Distribua a carga ou use mais de um token quando necessário.
Checklist de diagnóstico
- 401: confira o header
Authorization: Bearer ...e se o token não foi revogado. - 403: confira licença e o addon
api_access. - 404 inesperado: o ID provavelmente é de outro tenant — a API isola dados por tenant.
- 422: leia
errors; cheque obrigatórios e osin:(enums) de cada campo. Atenção adiscount_type: faturas usampercent, propostas usampercentage. - 400 ao enviar mensagem: canal de WhatsApp pode estar desconectado.
- Sempre envie
Accept: application/jsonpara receber erros em JSON.
api
erros
troubleshooting
http
status code
integração