Meu template não chegou: os dois momentos em que o envio falha no WhatsApp e o que cada código de erro está dizendo
A falha de um template pode aparecer na resposta imediata da API ou só depois, num webhook de status. O canal em que o erro surge já indica a família do problema, e a documentação da Meta é explícita: trate sempre pelo código numérico, nunca pelo título, que será descontinuado.
Por que meu template do WhatsApp não foi entregue?
A primeira pergunta a responder não é qual foi o erro, e sim onde ele apareceu. Um disparo de template pela Cloud API pode falhar em dois momentos distintos, e cada um aponta para uma família diferente de causas. Errar essa triagem é o motivo mais comum de times ficarem horas investigando o lado errado do problema.
No primeiro momento, a falha vem na resposta imediata da chamada, com HTTP 4xx ou 5xx, trazendo os campos code e message. O template nem chega a ser processado. Esse canal captura erro de validação, de permissão e de limite de velocidade.
No segundo momento, a chamada inicial deu certo, com HTTP 200 e message_status igual a accepted, mas a entrega falha depois. A notícia ruim chega por um webhook de status, com status igual a failed e um código dentro do array de erros. Esse canal captura template não enviável, limites e condição do destinatário.
As fontes deste texto são a referência de códigos de erro e a documentação de tempo de vida de mensagem da WhatsApp Business Platform, espelhadas e traduzidas internamente pelo AI Hub Brasil em 21 de maio de 2026.
Trate o erro pelo código, nunca pelo título
Essa é uma instrução explícita da documentação, e vale como regra de arquitetura para qualquer integração séria. Os títulos de erro serão descontinuados pela Meta, então qualquer lógica de retentativa, alerta ou opt-out que dependa do texto do título vai quebrar em silêncio quando isso acontecer.
Roteie a decisão pelo campo numérico do erro e use o detalhe textual apenas para log e diagnóstico. Nunca compare o título do erro em uma condição de código. Síntese da referência de códigos de erro da WhatsApp Business Platform
Quando o problema é o destinatário
Esta é a família que mais aparece em operação de volume no Brasil, e a que mais gera retentativa inútil. Vários desses códigos significam que a mensagem nunca vai passar, por mais que você tente.
| Código | Significado | O que fazer |
|---|---|---|
131026 | Mensagem não entregável: o número não tem WhatsApp, a pessoa não aceitou os novos termos, ou usa uma versão antiga do aplicativo. | Confirmar por outro canal. Não reenviar no automático. |
131050 | O destinatário pediu para parar de receber mensagens de marketing da sua empresa. | Nunca reenviar. Assinar o webhook de preferências do usuário para saber se ele volta a aceitar. |
130403 | A empresa bloqueou o usuário final no WhatsApp. | Desbloquear antes de qualquer reenvio. |
131047 | Passaram mais de 24 horas desde a última resposta e a janela de conversa livre fechou. | Reabrir a conversa com um template aprovado, não com mensagem livre. |
131021 | Remetente e destinatário são o mesmo número. | Corrigir o destinatário. |
130472 | O número faz parte de um experimento de mensagens de marketing da Meta. | Comportamento esperado do experimento, não é erro real. |
Há ainda um caso sem código próprio que confunde muita gente: a plataforma não entrega template de marketing para usuários com número dos Estados Unidos. Não existe erro específico para isso, simplesmente não se envia.
Quando o problema é a sua conta ou o seu ritmo de envio
| Código | Significado | O que fazer |
|---|---|---|
130429 | Limite de vazão da Cloud API atingido, em mensagens por segundo. | Espaçar os envios e reduzir a frequência. |
131048 | Linha freada por spam: mensagens anteriores foram bloqueadas ou marcadas como spam. | Verificar a qualidade da linha e melhorar o conteúdo antes de tentar de novo. |
131056 | Limite entre o par empresa e consumidor: mensagens demais do mesmo remetente para o mesmo destinatário em pouco tempo. | Aguardar antes de reenviar para esse contato. Outros números seguem funcionando. |
131064 | Limite de mensagens atingido por violações de classificação de template, como marcar marketing de utilidade. | Corrigir as categorias. A restrição é levantada ao fim do período de enforcement. |
131042 | Problema de elegibilidade de pagamento: linha de crédito estourada ou inativa, moeda ou fuso ausentes. | Ajustar o faturamento da conta. |
131031 | Conta travada por violação, ou dado da requisição que não confere. | Consultar o painel de enforcement de política e a API de status de saúde. |
130497 | Conta impedida de enviar a usuários de determinados países para a sua categoria. | Conferir a política de países permitidos. |
190 | Token de acesso expirado. | Gerar um novo token e repetir o envio. |
Sobre ritmo: cada número de negócio pode enviar uma mensagem a cada 6 segundos para o mesmo usuário. É permitido um pico de até 45 mensagens em 6 segundos, mas esse pico empresta da cota futura, e a documentação recomenda tratar o estrangulamento subsequente com uma espera crescente, começando curta e multiplicando o intervalo a cada nova falha.
Por quanto tempo a Meta tenta entregar?
Quando a entrega não acontece na hora, o sistema retenta durante um prazo de validade da mensagem. Esgotado o prazo, a mensagem é descartada. Esse prazo tem valores padrão bem diferentes por categoria, e é aqui que muita operação perde mensagem sem entender.
| Categoria | Prazo padrão | Faixa configurável |
|---|---|---|
| Autenticação | 10 minutos | De 30 segundos a 15 minutos |
| Utilidade | 30 dias | De 30 segundos a 12 horas |
| Marketing | 30 dias | De 12 horas a 30 dias |
Duas implicações merecem atenção. A primeira: se o webhook de entrega não chegou antes de o prazo estourar, assuma que a mensagem foi descartada, prevendo uma folga porque pode haver atraso entre a falha e o aviso. A segunda: quando um template é reclassificado automaticamente de categoria, o prazo customizado é apagado e volta a nulo. Um template de utilidade com prazo ajustado para 12 horas que vira marketing perde esse ajuste sem avisar.
Roteiro de diagnóstico quando um template não entrega
- Verifique em que canal o erro apareceu: resposta imediata aponta para conta, formato ou API errada; webhook aponta para template, limites ou destinatário.
- Se a resposta trouxe
held_for_quality_assessment, a mensagem está retida por avaliação de qualidade, e não falhou ainda. - Confirme se o template está aprovado e com nota de qualidade saudável antes de investigar qualquer outra hipótese.
- Leia o campo numérico do erro somado ao detalhe textual, e localize a família na tabela correspondente.
- Cheque a saúde da conta: enforcement de política, faturamento e status de saúde.
- Cheque os limites: vazão, limite por usuário e limite entre o par empresa e consumidor.
- Cheque a elegibilidade do destinatário: se não bloqueou, se não pediu para parar o marketing e se o número tem WhatsApp ativo.
- Se nenhum código apareceu e a entrega não foi confirmada dentro do prazo de validade, assuma descarte por prazo esgotado.
Se vários templates diferentes caem nos mesmos códigos ligados a qualidade e a limite por usuário, o problema de fundo não é técnico. É baixo engajamento e baixa taxa de leitura, e o tratamento é de conteúdo e de segmentação, não de integração. Vale checar também se o canal está montado sobre a conta oficial, já que soluções alternativas não expõem esses códigos: a diferença está no comparativo de API oficial e não oficial do WhatsApp.
Leitura crítica
A documentação de erros da WhatsApp Business Platform é boa no que descreve e omissa no que interessa para decidir. Ela diz o que cada código significa, mas raramente diz por quanto tempo a condição dura. O caso mais incômodo é o do limite por usuário: a orientação é esperar pelo menos 24 horas, com a ressalva de que pode falhar de novo enquanto o limite estiver ativo, sem que exista forma de consultar se ainda está.
Essa opacidade empurra o mercado para uma prática ruim, a retentativa cega, que a própria plataforma pune. Reenviar no código errado é uma das formas mais rápidas de degradar a reputação de um número, e ainda assim é o comportamento padrão de boa parte das ferramentas de disparo vendidas no Brasil. Vale perguntar ao seu fornecedor qual é a política de retentativa por código, e não aceitar "o sistema tenta de novo" como resposta.
O ponto positivo, e ele é real, está na separação clara entre falha síncrona e falha assíncrona. Quem estrutura o log nesses dois canais desde o início consegue responder à pergunta "por que não chegou" em minutos, e não em uma tarde de investigação. É uma decisão de arquitetura barata no começo e cara de remendar depois.