Códigos de erro da Cloud API do WhatsApp: significado e solução

Este guia é para desenvolvedores e equipes de operações de mensageria que veem mensagens do WhatsApp falhando e precisam saber rapidamente se devem corrigir a requisição, esperar, trocar o tipo de mensagem ou parar. Cada código abaixo foi conferido com a referência de códigos de erro da Cloud API da Meta; códigos e textos mudam, então confirme nessa página antes de fixar lógica no código.

Onde aparecem os erros da Cloud API do WhatsApp?

Os erros aparecem em dois lugares, e você precisa capturar os dois. Erros de requisição voltam imediatamente na resposta da API; erros de entrega chegam depois em um webhook de status.

• Erros síncronos. A requisição de envio é rejeitada e a resposta traz um objeto error com code, message, type e, muitas vezes, error_data.details. Exemplos típicos são tokens expirados, parâmetros ausentes e divergências de modelo.
• Erros assíncronos. A requisição de envio funciona e retorna um ID de mensagem, mas um webhook posterior informa status: failed com um array errors. Exemplos típicos são janelas de atendimento fechadas, destinatários inalcançáveis e limites de marketing.

Um erro comum é registrar apenas a resposta HTTP. As equipes acreditam que uma campanha deu certo porque toda requisição devolveu um ID de mensagem, enquanto centenas de mensagens falharam nos webhooks. Para entender como os status se relacionam, veja enviado, entregue, lido e falhou explicados.

Quais são os códigos de erro mais comuns do WhatsApp?

A tabela lista os códigos que a maioria das equipes encontra, agrupados pelo que fazer em seguida. As descrições parafraseiam a referência da Meta.

Como corrigir os erros que causam a maioria das campanhas com falha?

Na prática, poucos códigos causam a maior parte das falhas. Cada um tem uma regra de decisão clara.

131047: a janela de atendimento está fechada

O cliente escreveu pela última vez há mais de 24 horas. Texto livre, mídia e mensagens interativas só são permitidos dentro da janela de atendimento de 24 horas; fora dela é preciso usar um modelo aprovado; veja a janela de atendimento de 24 horas. Os agentes costumam esbarrar nisso ao responder a um chat antigo. Mostre aos agentes o status da janela e ofereça um seletor de modelos quando ela expirar.

131026: mensagem não entregável

Comece pela higiene dos números: formato internacional, código de país correto, sem zero à esquerda depois do código. Depois aceite que alguns números simplesmente não estão no WhatsApp ou usam uma versão antiga do app. Para mensagens críticas em tempo, como OTPs, recorra ao SMS. Veja WhatsApp vs SMS vs RCS.

131049 e 131050: limites de marketing e descadastros (opt-outs)

Ambos afetam mensagens de marketing. O 131050 é a escolha explícita do usuário de parar de receber marketing; suprima esses contatos para marketing e assine o webhook de preferências do usuário da Meta. O 131049 significa que a Meta optou por não entregar para proteger o engajamento do usuário; a Meta recomenda esperar pelo menos 24 horas, e tentativas mais cedo provavelmente falharão de novo. Reduza a frequência e melhore a relevância em vez de reenviar.

130429, 131048 e 131056: envio rápido demais ou em excesso

O 130429 é de throughput: enfileire as mensagens e aplique backoff. O 131056 é por par: você está escrevendo para uma pessoa com frequência demais. O 131048 é um sinal de qualidade do número remetente e exige correção de conteúdo e segmentação, não uma nova tentativa. Veja limites de mensagens e classificação de qualidade.

132000, 132001 e 132012: divergências de modelo

Quase sempre são bugs de integração. O nome do modelo, o código de idioma (por exemplo ar versus en_US) e a quantidade de variáveis precisam corresponder exatamente ao que foi aprovado. Crie um teste que envie cada modelo com valores de exemplo sempre que ele for editado.

Uma política de repetição que você pode implementar

Use esta lista para classificar cada falha automaticamente.

1. Registre o código, o título, error_data.details, o ID da mensagem, o destinatário e o nome do modelo.
2. Nunca repita 131050, 131021, 132016, 368 e 131031. Avise imediatamente um administrador sobre 368 e 131031.
3. Corrija e depois repita erros de autorização (0, 190, 10), de parâmetros (131008, 131009, 135000), de modelo (132000 a 132015) e de cobrança (131042). Alerte a equipe responsável.
4. Aplique backoff e repita 130429, 4, 80007, 131016 e 131057, usando backoff exponencial com limite máximo.
5. Troque de canal ou de tipo de mensagem para 131047 (modelo) e 131026 (SMS ou e-mail).
6. Espere 24 horas ou mais no caso do 131049 e revise a frequência das campanhas.
7. Reporte as falhas por código nos relatórios de campanha, não como um único total de "falhas".

Exemplo prático: a promoção que falhou de uma varejista de Riad

Um exemplo sintético. A "Najd Home" envia um modelo de marketing a 20.000 clientes com opt-in. A API aceita todas as requisições, mas os webhooks de status mostram cerca de 1.400 falhas.

Agrupando por código, o quadro fica claro. O maior grupo é o 131049; por isso a equipe retira esses usuários dos dois envios seguintes e reduz a frequência semanal. Um grupo menor é o 131026; a análise mostra que muitos números estavam salvos com um zero local à esquerda, o que uma normalização resolve. Vários usuários com 131050 são suprimidos de marketing em definitivo. Alguns erros 130429 vieram da rajada inicial, e agora o envio é cadenciado por uma fila.

Erros comuns e limites honestos

• Tratar toda falha como passível de nova tentativa. Isso desperdiça verba e pode reduzir a qualidade.
• Fixar o texto da Meta no código. A Meta atualiza títulos e descrições; baseie a lógica no código numérico e mantenha uma tabela de consulta que você possa atualizar.
• Ignorar error_data.details. Ele costuma indicar o parâmetro exato com problema.
• Nem toda falha tem solução. Alguns destinatários não podem ser alcançados pelo WhatsApp, e a Meta não explica cada decisão de 131049. Planeje um canal alternativo.

Como a OmniChannels.ai ajuda

A OmniChannels.ai, com tecnologia da BroadNet Technologies, oferece às equipes relatórios de entrega nas visões resumida e avançada, com filtros e exportação em CSV, para que as mensagens com falha sejam analisadas por campanha. O fallback entre canais pode reenviar por RCS ou SMS quando o WhatsApp falha, e os modelos são pré-visualizados em um mockup de celular e acompanhados durante a aprovação, o que reduz erros de incompatibilidade. Os webhooks informam os status FAILED e REJECTED em um formato normalizado único, e a documentação pública para desenvolvedores inclui uma referência de erros e limites.