Porque é que uma mensagem do WhatsApp falhou: como ler o estado failed e os seus erros
Um webhook de estado failed significa que a Meta não conseguiu enviar nem entregar uma mensagem que a empresa enviou pela API. Chega ao campo messages com o estado failed e um array errors que contém code, title, message, error_data.details e href. O código indica o motivo: 131047 janela fechada, 131026 não entregável, 131049 limite de marketing, 131050 marketing interrompido, 131042 problema de pagamento.
A easyCoexistence liga o número da sua app WhatsApp Business à Cloud API da Meta através de Coexistence e passa os estados failed para o seu servidor, diretamente ou como reencaminhamentos assinados quando as automações estão ativas.
Passaram mais de 24 horas desde a última resposta do destinatário; a solução da Meta é enviar um template em vez disso.
Não entregue para manter saudável o envolvimento no ecossistema; espere pelo menos 24 horas antes de reenviar o template de marketing.
O destinatário escolheu deixar de receber mensagens de marketing da empresa; a Meta indica que não se deve repetir.
Um estado failed omite o array contacts, por isso correlacione a falha através de statuses.id.
A Meta cobra pelas mensagens quando são entregues, não quando são enviadas.
Como é um estado failed?
Como qualquer estado, mais o array errors. O array contacts está em falta, recipient_user_id é omitido quando a mensagem foi enviada para um número de telefone, e não há objeto pricing. Title e message têm o mesmo texto, error_data.details explica-o numa 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 interrompido pelo limite por utilizador:
{
"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"
}
]
}
]
}Que códigos de erro aparecem mais, e o que significam?
A Meta devolve erros na resposta de envio, num estado failed, ou em ambos, por isso o mesmo código pode chegar por qualquer dos caminhos, e a sua rotina de tratamento deve ler os dois locais. Estes são os códigos que explicam a maioria das mensagens que nunca chegam, com o motivo da própria Meta e a primeira coisa a tentar. A lista completa está na referência de códigos de erro da Meta:
Como deve uma rotina de tratamento reagir a cada tipo de falha?
Classifique o código em função do que fazer a seguir, antes de qualquer nova tentativa. Uma repetição generalizada transforma uma recusa de marketing em falhas repetidas e pode prolongar um bloqueio, enquanto descartar um erro temporário perde uma mensagem que teria sido entregue um minuto depois.
- Repetir com backoff: 131000 desconhecido, 131016 serviço indisponível, 130429 throughput atingido.
- Esperar primeiro: 131049, pelo menos 24 horas, porque as tentativas precoces podem bloquear esse utilizador até mais 24 horas.
- Mudar a mensagem: 131047 exige um template aprovado, porque a janela de 24 horas está fechada.
- Parar para este cliente: 131050, até chegar um resume de
user_preferences. - Corrigir a conta ou o conteúdo: 131042 pagamento, 131031 conta restringida, 131053 multimédia.
Que falhas aparecem apenas como estado failed?
As que a Meta decide depois de aceitar o pedido. O envio devolve um wamid, e a recusa chega mais tarde neste webhook. A Meta não entrega templates de marketing a utilizadores do WhatsApp com números de telefone dos Estados Unidos (+1 com indicativo de área dos EUA). Um template de marketing enviado a um cliente que deixou de receber mensagens de marketing é processado e depois reportado como falhado com 131050, e o limite de marketing por utilizador reporta 131049 da mesma forma.
Se o número não tiver destino de webhook, estas falhas não ficam visíveis em lado nenhum 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 num número em Coexistence?
Duas coisas importam. Primeiro, a janela de 24 horas aplica-se apenas à API. O guia de Coexistence da Meta diz que as mensagens enviadas a partir da app WhatsApp Business não estão sujeitas à janela de atendimento ao cliente. Por isso, depois de um 131047, o proprietário ainda pode responder a esse cliente a partir do telemóvel, enquanto o seu sistema envia um template aprovado.
Segundo, o throughput é fixo. Um número usado na app e na API ao mesmo tempo envia no máximo 20 mensagens por segundo, e ultrapassar esse valor devolve 130429. Tudo o resto se comporta como em qualquer número da Cloud API: o mesmo campo, o mesmo array errors, os mesmos códigos.
Como é que as automações e a sua IA veem uma falha?
Depende de quando a Meta diz não. Uma recusa no momento do envio, como 131047, falha o passo da automação: a execução mostra Failed com a mensagem da Meta no separador Runs, e o proprietário recebe um e-mail para poder responder ao cliente pessoalmente. As automações também verificam a janela antes de enviar uma resposta de texto livre e saltam com window_closed em vez de tentar.
Uma falha que a Meta reporta depois chega como estado failed ao seu URL de reencaminhamento ou destino direto, e a execução mantém-se como estava. Uma IA que enviou um template através do conector MCP vê o wamid e "sent: true". Peça ao seu sistema o estado desse wamid, ou peça ao assistente para executar get_number_health quando muitas mensagens falham ao mesmo tempo.
Erros comuns
- Repetir 131050 em ciclo. O cliente deixou de receber mensagens de marketing, por isso cada tentativa falha da mesma forma até ele voltar a aceitá-las.
- Reenviar um template de marketing 131049 em poucas horas. A Meta pede pelo menos 24 horas, e as tentativas precoces podem bloquear esse utilizador até mais 24 horas.
- Registar apenas o title. error_data.details contém o motivo específico, por isso guarde o código e os detalhes em conjunto com o wamid.
- Correr sem destino de webhook e julgar a entrega pela resposta de envio, que só diz que a Meta aceitou a mensagem.
Quando a resposta de uma automação é recusada no momento do envio, a execução mostra o erro da Meta e é enviado um e-mail, e cada número é monitorizado 24/7 quanto a desligamentos e quedas de qualidade. De US$ 9 a US$ 0.75 por número e por mês, a descer à medida que acrescenta números, com os primeiros 3 dias gratuitos.
Perguntas frequentes
A Meta cobra uma mensagem falhada?
A Meta indica nas páginas de preços que cobra pelas mensagens entregues, não pelas que são apenas enviadas. Um estado failed não traz objeto de pricing. As cobranças vão para a conta WhatsApp Business da própria empresa; a easyCoexistence nunca aplica qualquer margem.
O 131026 quer dizer 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 é demasiado antiga. A Meta sugere pedir ao cliente, por outro canal, que verifique esses pontos.
Porque é que recipient_user_id aparece em algumas falhas e noutras não?
A Meta omite-o num estado failed quando a mensagem foi enviada para um número de telefone. Quando enviou para o BSUID do cliente, a falha inclui-o, e pode faltar recipient_id.
Pode uma mensagem falhar depois de entregue?
A referência da Meta descreve failed como falha ao enviar ou entregar. Quando a mensagem chega ao dispositivo, os próximos estados que pode esperar são read, ou played no caso de mensagens de voz.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em