Métricas e análise
Mensagem não entregue na API do WhatsApp: os erros mais comuns e o que fazer
Os códigos de erro de envio da API do WhatsApp que mais aparecem, o que cada um significa e quando reenviar, corrigir ou parar. Pelos códigos documentados da Meta.
O sistema diz que enviou. O cliente diz que não recebeu. No meio do caminho existe um código de seis dígitos que quase ninguém lê: o erro devolvido pela Meta. Ele diz o que aconteceu e, mais importante, se vale a pena tentar de novo.
Este guia trata dos erros de envio, os que aparecem com o número já conectado e funcionando. Problemas na hora de conectar o número são outro assunto, tratado em erros comuns na coexistência.
Onde o erro aparece
Uma mensagem pode falhar em dois momentos:
- Na hora do envio, na resposta da API. A Meta recusa o pedido ali mesmo: template inexistente, variável faltando, ritmo acima do permitido.
- Depois, no webhook de status. A Meta aceitou o pedido, tentou entregar e não conseguiu. O status chega como
failed, com o código.
Às vezes o mesmo erro chega pelos dois caminhos. A Meta recomenda tratar a falha pelo código e pelo campo de detalhes, e não pelo título.
Uma boa notícia no meio da má: mensagem que falhou não é cobrada. A Meta cobra só mensagem entregue.
As três reações possíveis
Todo erro de envio cai numa destas caixas:
- Espere e tente de novo. O problema é de ritmo ou de momento.
- Corrija e reenvie. O problema está no pedido: template, variável, janela.
- Não reenvie. A pessoa não quer receber, não pode receber, ou a conta está impedida. Insistir piora.
A coluna "O que fazer" das tabelas abaixo segue essa lógica.
Janela, template e formato
| Código | O que significa | O que fazer |
|---|---|---|
| 131047 | Passaram mais de 24 horas desde a última mensagem do cliente; a janela fechou | Corrija: envie um template |
| 132001 | Template inexistente nesse idioma, ou ainda não aprovado | Confira nome, idioma e status |
| 132000 | O número de variáveis enviadas não bate com o template | Corrija o envio |
| 132012 | Variáveis no formato errado | Corrija o envio |
| 132005 | Texto traduzido longo demais | Encurte |
| 131051 | Tipo de mensagem não suportado | Mude o formato |
| 132007 | O conteúdo do template viola uma política do WhatsApp | Reescreva o template |
| 132015 | Template pausado por baixa qualidade | Pare e revise o texto e a lista |
| 132016 | Template pausado vezes demais; desativado de vez | Crie outro, depois de entender por que o anterior caiu |
Um caso típico do 131047: a automação tenta responder com texto livre a alguém que escreveu ontem. Quem abre a janela e quando ela fecha está em janela de 24 horas.
Pausa e desativação dependem de como as pessoas reagem ao template. Quem cria, aprova e acompanha cada um, numa operação com provedor, está em templates com Tech Provider.
Destinatário
| Código | O que significa | O que fazer |
|---|---|---|
| 131026 | Não deu para entregar: o número não tem WhatsApp, a pessoa não aceitou os termos atuais ou usa uma versão muito antiga do app | Não insista; confira se o número está certo |
| 131049 | Não entregue para manter o engajamento saudável: é o limite de marketing por pessoa | Espere pelo menos 24 horas |
| 131050 | A pessoa optou por não receber marketing da sua empresa | Não reenvie |
O 131049 tem uma armadilha própria: reenvios repetidos em menos de 24 horas podem bloquear novas tentativas para aquela pessoa. Ele está explicado em detalhe em limite de marketing por usuário.
Ritmo
| Código | O que significa | O que fazer |
|---|---|---|
| 130429 | Limite de vazão da Cloud API atingido | Reduza o ritmo e tente de novo |
| 131056 | Mensagens demais do mesmo número para a mesma pessoa em pouco tempo | Espace; para outros destinatários, siga enviando |
| 131057 | Conta em modo de manutenção, por exemplo durante um aumento de vazão | Espere e tente de novo |
Para dar escala: a vazão padrão é de até 80 mensagens por segundo por número, e números em coexistência ficam fixos em 20. Para a mesma pessoa, o ritmo é de uma mensagem a cada 6 segundos, com uma rajada curta que consome a cota seguinte. Quantas pessoas a empresa pode alcançar por dia é outra regra, explicada em limites de envio com Tech Provider.
Conta, pagamento e política
| Código | O que significa | O que fazer |
|---|---|---|
| 131042 | Problema na cobrança: forma de pagamento ou linha de crédito ausente, limite estourado, conta suspensa, fuso ou moeda não definidos | Resolva a cobrança na Meta antes de reenviar |
| 131048 | Envio restringido porque muitas mensagens anteriores foram bloqueadas ou marcadas como spam | Pare e confira a qualidade no WhatsApp Manager |
| 131064 | Conta limitada por classificar marketing como utilidade | A restrição sai sozinha depois do período; corrija as categorias |
| 131063 | Template de marketing bloqueado na Cloud API porque a empresa desligou o marketing nela | Use a Marketing Messages API |
| 130497 | Conta proibida de enviar para usuários de certos países | Não reenvie para esses países |
| 368 | Conta restringida ou desativada por violar uma política | Pare e entenda a violação |
| 131031 | Conta bloqueada por violação de política, ou dado do pedido que não confere, como o PIN de duas etapas | Confira o pedido; se for política, trate como restrição |
| 135000 | Erro desconhecido nos parâmetros; também marca mensagens descartadas quando a Meta suspeita de abuso num disparo grande | Revise o envio; se foi um disparo grande, pare |
Esta é a tabela que mais preocupa, porque fala da conta, e não de uma mensagem. O que cada tipo de restrição significa e como evitar está em número restrito ou banido.
Uma rotina de triagem
- Agrupe as falhas por código, não por cliente. Cem falhas com o mesmo código são um problema só.
- Comece pelos erros de conta: 131042, 131048, 368, 131031 e 131064. Enquanto eles não se resolvem, nenhum reenvio adianta.
- Depois, os de template e formato, a família 132. Uma correção resolve o envio inteiro.
- Por último, os de destinatário. Tire da lista de marketing quem deu 131050 e não insista em 131026.
- Reenvie uma vez, no tempo certo. Reenvio em loop agrava o 131049 e, no 131056, só repete o erro.
- Anote o que se repete. Falha que volta toda semana com o mesmo código é sinal de processo, não de azar.
O que o provedor resolve e o que não resolve
Um provedor pode mostrar o erro com clareza, organizar o reenvio no tempo certo e abrir chamado no suporte da Meta. Ele não desfaz restrição de conta, não aprova template e não aumenta limite. Essas decisões são da Meta e valem igual para qualquer provedor.
No Vazante
O Vazante é Tech Provider (provedor de tecnologia) da Meta e usa a API oficial do WhatsApp Business, a Cloud API. Com o número conectado, você cria e acompanha os templates e envia mensagens pelo painel. Regras de entrega, códigos de erro e cobrança continuam sendo da Meta, que cobra as mensagens entregues direto na sua conta, sem margem do Vazante. A coexistência vem incluída nos planos com assinatura ativa: veja a página do WhatsApp Coexistence.
Perguntas frequentes
Mensagem que deu erro é cobrada?
Não. A Meta cobra só mensagem entregue. Falha na hora do envio ou no webhook de status não entra na conta.
Qual erro aparece quando a janela de 24 horas já fechou?
O 131047. A partir daí, só dá para falar com a pessoa por template aprovado.
Devo reenviar automaticamente toda mensagem que falhar?
Não. Erro de ritmo pede espera, erro de template pede correção e erros como o 131050 pedem que você não reenvie. Reenvio automático sem olhar o código costuma piorar a situação.
Por que tratar o erro pelo código, e não pelo título?
Porque é o que a Meta recomenda: o código e o campo de detalhes são a referência estável, e o título é só a descrição.
Problema no cartão aparece como erro de envio?
Aparece como 131042, que reúne problemas na forma de pagamento da conta. Enquanto ele não for resolvido na Meta, reenviar não adianta.