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. |
Códigos de falha de entrega da Meta
Mensagens com status: "failed" podem trazer um código específico da Meta. Nas rotas de mensagens e destinatários de campanha, use delivery_error.code para automação e delivery_error.description para exibição em português. Os campos error_message e failure_reason preservam o texto bruto apenas por compatibilidade.
| Código | Significado em português |
|---|---|
| 130403 | Você bloqueou este contato no WhatsApp — desbloqueie para enviar |
| 130472 | Número em teste interno da Meta — sem ação disponível pelo operador |
| 131008 | Faltou um campo obrigatório no envio |
| 131009 | Valor inválido em um dos campos do envio |
| 131021 | Não é possível enviar mensagem pro próprio número |
| 131026 | Número não tem WhatsApp ativo |
| 131031 | Conta WhatsApp Business suspensa pela Meta |
| 131042 | Dados fiscais ou de pagamento incompletos na Meta |
| 131047 | Janela de 24h fechada — só dá pra usar template aprovado |
| 131049 | Meta limitou: usuário recebeu marketing demais (de várias empresas) |
| 131050 | Contato pediu para não receber marketing (opt-out) |
| 131051 | Tipo de mensagem não suportado neste número |
| 131053 | Falha no upload da mídia (formato ou link inválido) |
| 131056 | Limite de mensagens entre essas duas contas atingido |
| 131063 | Marketing desabilitado na configuração da conta |
| 132000 | Variáveis do template não batem com o esperado |
| 132001 | Template não existe |
| 132005 | Texto traduzido muito longo |
| 132007 | Conteúdo do template viola política da Meta |
| 132012 | Formato da variável não bate com o template |
| 132015 | Template pausado pela Meta |
| 132016 | Template desabilitado |
| 132068 | Flow bloqueado |
| 132069 | Flow com throttle |
| 133000 | Erro de registro da conta WhatsApp Business |
| 133004 | Servidor da Meta indisponível temporariamente |
| 133005 | PIN de verificação em duas etapas incorreto |
| 133006 | Número precisa ser verificado antes de registrar |
| 133008 | Muitas tentativas de PIN — aguarde o tempo indicado |
| 133009 | PIN inserido rápido demais — aguarde |
| 133010 | Número não registrado na Meta |
| 133015 | Número recém-deletado — aguarde alguns minutos |
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.