Guia de Códigos de Erro da API do WhatsApp Business: Como Identificar e Resolver Falhas

A integração com a API Cloud do WhatsApp Business é uma das formas mais eficientes de engajar e autenticar usuários em escala. No entanto, para desenvolvedores e equipes de engenharia, lidar com falhas de entrega de mensagens ou erros de autorização de forma resiliente é um requisito indispensável para garantir a estabilidade do sistema. A API oficial da Meta retorna cabeçalhos de resposta estruturados em formato JSON sempre que uma requisição falha. Compreender o que cada código de erro significa por trás dos panos pode poupar dezenas de horas de depuração (debugging) e evitar bloqueios na fila de disparos da sua aplicação.

Neste guia técnico completo, apresentamos os erros mais comuns divididos por categorias (erros de parâmetros, autenticação, limites de taxa e templates), explicamos como depurar esses retornos de forma pragmática e demonstramos boas práticas de tratamento de erros com exemplos práticos em JavaScript.

---

1. A Estrutura de Retorno de Erros da Meta

Sempre que uma chamada HTTP para a API do WhatsApp Business falha, os servidores da Meta respondem com um código de status HTTP correspondente (como 400 Bad Request, 401 Unauthorized ou 429 Too Many Requests) e um payload JSON detalhando a causa do problema.

Abaixo está o esquema padrão de um payload de erro retornado pela API Cloud:

json { "error": { "message": "(#131030) Recipient phone number not in active account allowed list.", "type": "OAuthException", "code": 131030, "error_data": { "messaging_product": "whatsapp", "details": "Recipient phone number is not verified. Please register the number in your Meta developer account." }, "fbtrace_id": "AP_8aBcdEfGhIjKlMnOp123" } } 

Ao inspecionar o retorno, o desenvolvedor deve focar em três campos cruciais: - code: O identificador numérico principal do erro. - message: Descrição legível do erro fornecida pela Meta. - fbtrace_id: O identificador exclusivo da transação no ecossistema do Facebook, necessário caso você precise abrir um ticket de suporte diretamente com a Meta.

---

2. Catálogo de Códigos de Erro Comuns e Soluções

Abaixo compilamos uma tabela exaustiva dos códigos de erro mais comuns na API do WhatsApp Business com suas respectivas ações corretivas:

Código do Erro	Mensagem / Tipo do Erro	Razão Técnica da Falha	Como Resolver
:---	:---	:---	:---
100	Invalid Parameter	Parâmetro obrigatório em falta, mal formatado ou tipo incorreto no JSON payload.	Verifique se o número do destinatário está no formato E.164. Certifique-se de que os parâmetros dinâmicos do template condizem com as variáveis configuradas.
190	Invalid OAuth Access Token	O token de acesso do sistema (Access Token) expirou, foi revogado ou é inválido para a conta informada.	Gere um novo token de acesso permanente nas configurações do Meta Business Suite e atualize suas variáveis de ambiente.
131009	Parameter Value is Invalid	O nome do template informado na API não corresponde a um template aprovado ou o idioma selecionado não está ativo.	Acesse o gerenciador de templates e confira se o nome está escrito de forma idêntica (case-sensitive) e se o idioma está aprovado.
131021	Sender/Receiver Pair Blocked	O destinatário marcou a sua conta como spam ou bloqueou o número comercial nas configurações do próprio WhatsApp.	Pare de enviar mensagens promocionais para este contato imediatamente. Tente reatar o contato físico apenas com opt-in explícito fora do canal.
131030	Recipient Not in Allowed List	Conta de testes (Sandbox) tentando enviar mensagens para números que não foram autorizados no painel de desenvolvedor.	Vá ao console de desenvolvedor da Meta e cadastre o número do destinatário na lista de celulares de teste autorizados, ou verifique sua empresa.
130429	Rate Limit Exceeded	O número de mensagens enviadas por segundo (MPS) ou minuto excedeu o limite do seu nível atual (Throughput).	Implemente uma fila de mensageria assíncrona (como RabbitMQ ou BullMQ) para limitar a taxa de requisições por segundo.
131047	More than 24h since last message	Tentativa de envio de mensagem de texto livre após a janela de conversação de 24 horas ter expirado.	Envie um template de mensagem de utilidade ou marketing aprovado para reabrir a janela de conversação de 24 horas.
132001	Template is Paused	O template foi pausado automaticamente pela Meta devido a avaliações negativas dos usuários finais.	Ajuste o conteúdo do template para torná-lo mais relevante e solicite uma nova análise da Meta após o período de punição.

---

3. Gestão de Limites de Envio (Rate Limits & Messaging Limits)

Um dos erros mais comuns em campanhas de alta escala no Brasil é o Erro 130429 (Rate Limit Exceeded). A Meta gerencia os limites de mensagens em duas camadas diferentes:

A. Limites de Taxa de Envio (Throughput)

A Cloud API possui limites padrão de mensagens enviadas por segundo (geralmente 80 MPS para contas padrão com números de telefone de alta capacidade). Se o seu servidor disparar 1.000 requisições HTTP simultâneas em um único segundo sem enfileiramento, a Meta responderá com erros 429 para a maior parte das chamadas.

B. Níveis de Limite de Mensagens (Messaging Limits)

O Messaging Limit determina para quantos clientes únicos a sua empresa pode enviar mensagens por dia. Existem quatro níveis principais: - Nível 1 (Tier 1): Permite enviar mensagens para até 1.000 clientes únicos por dia. - Nível 2 (Tier 2): Permite enviar mensagens para até 10.000 clientes únicos por dia. - Nível 3 (Tier 3): Permite enviar mensagens para até 100.000 clientes únicos por dia. - Nível 4 (Tier 4): Envio ilimitado de mensagens por dia.

Para subir de nível automaticamente, o volume de envios diários deve alcançar a metade do limite do seu nível atual nos últimos 7 dias, mantendo uma classificação de qualidade de número comercial alta (ou seja, sem sofrer marcações excessivas de spam ou denúncias).

Aprenda a otimizar sua entrega de mensagens de autenticação com segurança em WhatsApp Auth API e confira os detalhes técnicos do nosso ecossistema de APIs em WhatsApp Business API.

---

4. Implementação Prática: Tratamento de Erros Resiliente em Node.js

Para evitar perdas de mensagens importantes, as equipes de engenharia devem implementar lógicas de tentativas automáticas com recuo exponencial (Exponential Backoff) e sistemas de fallback robustos.

Abaixo demonstramos uma função de envio de templates utilizando Node.js que captura erros de Rate Limit da Meta e realiza tentativas com delay dinâmico, além de direcionar para failover:

javascript const axios = require('axios');

async function sendWhatsAppMessageWithRetry(payload, retries = 3, delay = 1000) { const url = 'https://graph.facebook.com/v19.0/sua-phone-number-id/messages'; const token = process.env.WHATSAPP_TOKEN;
try { const response = await axios.post(url, payload, { headers: { 'Authorization': Bearer ${token}, 'Content-Type': 'application/json' } }); return response.data; } catch (error) { if (error.response) { const { code, message } = error.response.data.error; console.error(Erro da API do WhatsApp (Código ${code}): ${message});
// Caso seja erro de Rate Limit (130429) ou erro interno temporário (131000) if ((code === 130429 || code === 131000) && retries > 0) { console.warn(Tentativa falhou. Aguardando ${delay}ms para tentar novamente... (Tentativas restantes: ${retries})); await new Promise(resolve => setTimeout(resolve, delay)); return sendWhatsAppMessageWithRetry(payload, retries - 1, delay * 2); // Recuo exponencial }
// Se a janela de 24h estiver fechada (131047), lançar trigger de fallback if (code === 131047) { console.warn('Janela de 24h fechada. Encaminhando para fallback via SMS OTP...'); return triggerSmsFallback(payload.to, 'Seu token de segurança expirou. Acesse a conta corporativa.'); } } throw new Error('Falha definitiva no envio do WhatsApp.'); } }
async function triggerSmsFallback(phoneNumber, message) { // Chamada fictícia de API de SMS do BSP parceiro console.log(SMS Fallback acionado com sucesso para ${phoneNumber}: ${message}); return { status: 'sent_via_sms' }; } 

---

5. Conclusão

Ter uma estratégia resiliente de monitoramento de erros é o diferencial entre uma integração instável e um canal de comunicação de alto rendimento. Sempre que desenvolver integrações com o WhatsApp, certifique-se de tratar os retornos da Meta usando webhooks de status de mensagens em tempo real para verificar se o código foi de fato entregue e lido. Em caso de dúvidas sobre como estruturar a infraestrutura de comunicação ou caso queira terceirizar o tratamento complexo de retries e rotas Tier-1 para um provedor gerenciado nacional, entre em contato com nosso time de suporte especializado ou crie sua sandbox de testes em nossa API unificada.