Por que uma mensagem do WhatsApp falhou: como ler o status failed e seus erros
Um webhook de status failed significa que a Meta não conseguiu enviar ou entregar uma mensagem que a empresa enviou pela API. Ele chega no campo messages com status failed e um array errors com code, title, message, error_data.details e href. O code indica o motivo: 131047 janela fechada, 131026 impossível de entregar, 131049 limite de marketing, 131050 marketing interrompido, 131042 problema de pagamento.
O easyCoexistence conecta o número do seu app do WhatsApp Business à Cloud API da Meta pela Coexistência e repassa os status failed para o seu servidor, diretamente ou como encaminhamentos assinados quando as automações estão ativas.
Já se passaram mais de 24 horas desde a última resposta do destinatário; a solução da Meta é enviar um template.
Não entregue para manter saudável o engajamento do ecossistema; espere pelo menos 24 horas antes de reenviar o template de marketing.
O destinatário escolheu parar de receber mensagens de marketing da empresa; a Meta orienta não repetir.
Um status failed não traz o array contacts, então correlacione a falha pelo statuses.id.
O que a Meta cobra: as mensagens são cobradas quando entregues, não quando enviadas.
Como é um status failed?
Igual a qualquer status, mais o errors. O array contacts não vem, o recipient_user_id é omitido quando a mensagem foi enviada para um número de telefone, e não há objeto pricing. title e message trazem o mesmo texto, error_data.details explica o problema em uma frase, e href aponta para a lista de códigos de erro da Meta. Este é o exemplo da própria Meta, um template de marketing barrado pelo limite por usuário:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
"status": "failed",
"timestamp": "1751142888",
"recipient_id": "16505551234",
"errors": [
{
"code": 131049,
"title": "This message was not delivered to maintain healthy ecosystem engagement.",
"message": "This message was not delivered to maintain healthy ecosystem engagement.",
"error_data": {
"details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
},
"href": "/documentation/business-messaging/whatsapp/support/error-codes"
}
]
}
]
},
"field": "messages"
}
]
}
]
}Quais códigos de erro aparecem com mais frequência e o que significam?
A Meta retorna erros na resposta do envio, em um status failed ou nos dois, então o mesmo código pode chegar por qualquer um dos caminhos, e seu handler deve ler os dois lugares. Estes são os códigos que explicam a maioria das mensagens que nunca chegam, com o motivo dado pela própria Meta e a primeira coisa a tentar; a lista completa está na referência de códigos de erro da Meta:
Como um handler deve reagir a cada tipo de falha?
Antes de qualquer nova tentativa, classifique o código pelo que fazer em seguida. Repetir tudo indiscriminadamente transforma uma saída da lista de marketing em falhas repetidas e pode prolongar um bloqueio, enquanto descartar um erro temporário faz perder uma mensagem que teria passado um minuto depois.
- Repetir com backoff: 131000 desconhecido, 131016 serviço indisponível, 130429 throughput atingido.
- Esperar antes: 131049, pelo menos 24 horas, já que repetir cedo demais pode bloquear esse usuário por mais até 24 horas.
- Trocar a mensagem: 131047 exige um template aprovado, porque a janela de 24 horas está fechada.
- Parar de enviar para este cliente: 131050, até chegar um
user_preferencescom resume. - Corrigir a conta ou o conteúdo: 131042 pagamento, 131031 conta restrita, 131053 mídia.
Quais falhas aparecem só como status failed?
As que a Meta decide depois de aceitar a requisição. O envio retorna um wamid, e a recusa chega depois por este webhook. A Meta não entrega templates de marketing a usuários do WhatsApp com números de telefone dos Estados Unidos (+1 com código de área dos EUA), um template de marketing para um cliente que parou de receber mensagens de marketing é processado e depois reportado como failed com 131050, e o limite de marketing por usuário reporta 131049 da mesma forma.
Se o número não tiver um destino de webhook, essas falhas não aparecem em nenhum lugar visível para você, e a mensagem simplesmente parece enviada. Para a ordem completa de verificações quando um cliente não recebeu nada, veja a página sobre mensagens da API do WhatsApp que não foram entregues.
O que muda em um número com Coexistência?
Duas coisas importam. Primeiro, a janela de 24 horas vale só para a API. O guia de Coexistência da Meta diz que mensagens enviadas pelo app do WhatsApp Business não estão sujeitas à janela de atendimento, então depois de um 131047 o dono ainda pode responder esse cliente pelo celular, enquanto seu sistema envia um template aprovado.
Segundo, o throughput é fixo. Um número usado no app e na API ao mesmo tempo envia no máximo 20 mensagens por segundo, e passar disso retorna 130429. Todo o resto se lê igual a qualquer número da Cloud API: mesmo campo, mesmo array errors, mesmos códigos.
Como as automações e sua IA enxergam uma falha?
Depende de quando a Meta recusa. Uma recusa no momento do envio, como 131047, faz a etapa da automação falhar: a execução aparece como Failed com a mensagem da Meta na aba Runs, e o dono recebe um e-mail para responder esse cliente pessoalmente. As automações também verificam a janela antes de enviar uma resposta em texto livre e pulam com window_closed em vez de tentar.
Uma falha que a Meta reporta depois chega como status failed na sua Forward URL ou no destino direto, e a execução fica como estava. Uma IA que enviou um template pelo conector MCP vê o wamid e "sent: true"; consulte no seu sistema o status desse wamid, ou peça ao assistente para executar get_number_health quando muitas mensagens falharem ao mesmo tempo.
Erros comuns
- Repetir 131050 em loop. O cliente parou de receber mensagens de marketing, então cada tentativa falha do mesmo jeito até ele voltar a aceitá-las.
- Reenviar em poucas horas um template de marketing que deu 131049. A Meta pede pelo menos 24 horas, e repetir cedo demais pode bloquear esse usuário por mais até 24 horas.
- Registrar só o title. O error_data.details traz o motivo específico, então guarde code e details junto com o wamid.
- Operar sem destino de webhook e avaliar a entrega pela resposta do envio, que só diz que a Meta aceitou a mensagem.
Quando a resposta de uma automação é recusada no envio, a execução mostra o erro da Meta e você recebe um e-mail, e todo número é monitorado 24/7 contra desconexões e quedas de qualidade. De R$ 29,90 a R$ 3,90 por número por mês, caindo conforme você adiciona números, com os 3 primeiros dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
A Meta cobra por mensagem que falhou?
As páginas de preços da Meta dizem que ela cobra pelas mensagens entregues, não pelas mensagens apenas enviadas. Um status failed não traz objeto pricing. As cobranças vão para a própria WhatsApp Business Account da empresa; o easyCoexistence nunca aplica margem.
O erro 131026 significa que o cliente bloqueou a empresa?
A lista da Meta para o 131026 aponta outros motivos: o número não está no WhatsApp, o destinatário não aceitou os termos mais recentes ou a versão do WhatsApp dele é antiga demais. A Meta sugere falar com o cliente por outro canal para verificar esses pontos.
Por que o recipient_user_id aparece em algumas falhas e em outras não?
A Meta o omite em um status failed quando a mensagem foi enviada para um número de telefone. Quando você enviou para o BSUID do cliente, a falha o inclui, e quem pode faltar é o recipient_id.
Uma mensagem pode falhar depois de entregue?
A referência da Meta define failed como falha ao enviar ou entregar. Depois que a mensagem chega ao aparelho, os próximos status que você pode esperar são read, ou played no caso de mensagens de voz.
Continue lendo
Pronto para começar?
Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.
Começar teste grátisVerificado em