Erros
O formato canônico de erro da API v1 e os códigos transversais a todos os endpoints.
Toda resposta de erro da API v1 segue o mesmo formato: um objeto JSON com success: false, uma mensagem legível em error e um código estável em code — use code para tratamento programático, não a mensagem.
{
"success": false,
"error": "Permissão insuficiente para esta operação",
"code": "INSUFFICIENT_SCOPE",
"required_scope": "contacts:write"
}Códigos transversais
| Código | HTTP | Quando ocorre |
|---|---|---|
| UNAUTHORIZED | 401 | Token ausente ou inválido. |
| FORBIDDEN | 403 | A empresa dona da chave está inativa. |
| INSUFFICIENT_SCOPE | 403 | A chave não tem o escopo exigido pelo endpoint — o campo required_scope indica qual. |
| PLAN_REQUIRED | 403 | O recurso exige um plano superior (ex.: Enterprise) ao da empresa. |
| VALIDATION_ERROR | 422 | O corpo da requisição não passou na validação — o campo details traz o erro por campo. |
| RATE_LIMITED | 429 | A chave excedeu o limite de requisições por minuto. |
| NOT_FOUND | 404 | O recurso não existe — inclusive quando o ID pertence a outra empresa (nunca revela dados de terceiros). |
| INTERNAL_ERROR | 500 | Erro inesperado no servidor. |
Duas exceções ao formato canônico: (1) o erro 429 gerado pela camada de infraestrutura (limite por IP, antes de chegar na sua chave) devolve apenas { "error": "Too many requests" }, sem code; (2) os endpoints de webhooks têm formato próprio de resposta — sucesso { "ok": true }, erro { "error": "...", "code": "..." } — não o envelope success/error/code desta seção.
Nas rotas legadas de campanha E de envio (/send/message, /send/template), erros 500 usam o código PROVIDER_ERROR em vez de INTERNAL_ERROR — trate ambos como falha interna não recuperável pelo cliente.