Códigos de Erro
Referência completa dos códigos HTTP e formato de resposta de erro.
Formato Padrão de Erro
Todas as respostas de erro seguem o formato ApiErrorResponse:
| Campo | Tipo | Descrição |
|---|---|---|
status | integer | Código HTTP da resposta |
error | string | Tipo do erro (derivado do status) |
message | string | Descrição detalhada do erro |
timestamp | string | Data/hora do erro (ISO 8601) |
Códigos HTTP
| Código | Tipo | Descrição | Exemplo |
|---|---|---|---|
400 | Bad Request | Dados inválidos ou ausentes | Campo obrigatório não preenchido |
401 | Unauthorized | Credenciais inválidas | API Key incorreta ou JWT expirado |
402 | Payment Required | Saldo insuficiente | Aplicação sem créditos para envio |
403 | Forbidden | Acesso negado | Usuário sem permissão para o recurso |
404 | Not Found | Recurso não encontrado | Mensagem ou aplicação inexistente |
500 | Internal Server Error | Erro interno do servidor | Falha na comunicação com o provider WhatsApp |
Erros de Validação (400)
Erros de validação de campos retornam a mensagem específica do campo inválido:
Validações comuns:
"Telefone é obrigatório"— campo telefone ausente ou vazio"Mensagem é obrigatória"— campo mensagem ausente ou vazio- Formato de telefone inválido — deve incluir DDI (ex:
+5511999999999)
Erro de Saldo Insuficiente (402)
Retornado ao tentar enviar mensagem sem saldo suficiente. Formato especial:
Erros do provider WhatsApp
O envio de WhatsApp é agnóstico de provider: cada aplicação usa Twilio ou Meta Cloud API. Independentemente do provider, os erros são registrados nos mesmos campos errorCode e errorMessage da mensagem, capturados no callback de status (webhook).
Twilio
Códigos comuns retornados pela Twilio:
| Código | Descrição |
|---|---|
21211 | Número de telefone inválido |
21408 | Permissão negada para enviar ao número |
21610 | Destinatário optou por não receber mensagens (opt-out) |
63016 | Número não registrado no WhatsApp |
63032 | Conta sandbox — destinatário precisa aceitar sandbox |
Meta Cloud API
Quando a aplicação usa a Meta Cloud API (Graph API direta), os erros vêm no campo error.code da resposta de envio e em statuses[].errors[].code do webhook de status. Códigos reconhecidos pela plataforma:
| Código | Descrição |
|---|---|
190 | Access Token inválido ou expirado — gere um token permanente de Usuário do Sistema e atualize as credenciais |
200 / 10 / 299 | Permissão insuficiente sobre a WhatsApp Business Account (WABA) |
100 | Parâmetro/identificador inválido — verifique o Phone Number ID e o WABA ID |
131030 | Número do destinatário não está na lista de testes (app ainda não publicado) |
131026 | Mensagem não entregue — destinatário pode não ter WhatsApp ou o número é inválido |
131047 | Fora da janela de 24h — use um template (HSM) aprovado para reabrir a conversa |
131056 | Limite de frequência para este par (remetente/destinatário) atingido |
80007 / 4 | Limite de requisições (rate limit) da API atingido |
133010 | Número não registrado na Cloud API — conclua o registro do número (PIN) |
(#código) mensagem conforme a Graph API. Referência completa: Meta WhatsApp Cloud API — Error Codes.Bloqueio automático de número
Falhas repetidas com códigos sensíveis fazem a plataforma retirar o número do pool de envio (status BLOQUEADO_META), protegendo a reputação. A contagem é uma janela de 1h; ao atingir o limiar (padrão 10), o número é bloqueado e a reativação é manual. Códigos sensíveis padrão: 63018, 63021, 30007 (Twilio) e 131048, 131031, 368 (Meta) — configuráveis.