Códigos de erro da API do WhatsApp (Cloud API)
Estes são os códigos que a Meta devolve quando recusa ou não entrega uma mensagem da Cloud API. São diferentes dos códigos do próprio CRPRO Hub, como META_SEND_FAILED, que estão em erros da API. A Meta pede que o tratamento seja feito pelo número do código e pelo texto de error_data.details: ela não publica mais título nem status HTTP por código, e avisa que o título vai ser descontinuado.
Como o erro chega pelo CRPRO Hub
A Meta pode recusar na hora, na resposta da chamada, ou depois, avisando por webhook — e às vezes pelos dois caminhos. No CRPRO Hub isso aparece de duas formas:
Na resposta do envio
Quando a Meta recusa na própria chamada, o envio responde 502 com o código da Meta em details.meta_code. O texto de error_data.details ainda não é repassado nessa resposta.
{
"error": {
"code": "META_SEND_FAILED",
"message": "A Meta recusou o envio da mensagem.",
"details": {
"meta_code": 131026
}
}
}Depois, no webhook
Quando a recusa vem depois do 202, ela chega no evento message.status com status: "failed", e o array errors vem como a Meta mandou, com error_data.details. O histórico do canal (GET /api/v1/channels/{id}/messages) guarda o código no campo error_code. Para receber esse evento, o endpoint de webhook precisa assinar message.status — veja receber mensagens.
{
"id": "7a2c9e10-4b3d-4f5e-8a6b-1c2d3e4f5a6b",
"event": "message.status",
"channel_id": "9f6a9c1e-2f3d-4a5b-8c7d-1e2f3a4b5c6d",
"occurred_at": "2026-10-03T12:00:00.000Z",
"data": {
"message_id": "wamid.EXEMPLO456",
"status": "failed",
"recipient_id": "5521999999999",
"conversation": null,
"pricing": null,
"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": "https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes/"
}
]
}
}202 do envio quer dizer aceito e enfileirado, não entregue. Quem só olha a resposta da chamada não vê a maior parte das falhas de entrega: elas chegam no message.status.Entrega e janela de atendimento
A mensagem foi aceita, mas não chegou ao contato.
131026 — A mensagem não pôde ser entregue ao contato.
Descrição na tabela de códigos da MetaUnable to deliver message. Reasons can include: the recipient phone number is not a WhatsApp phone number; recipient has not accepted the new Terms of Service and Privacy Policy; recipient using an old WhatsApp version
Por quê: O número não tem WhatsApp, o contato não aceitou os termos de uso mais recentes ou usa uma versão antiga do aplicativo.
O que fazer: Confirme o número por outro canal e peça ao contato que aceite os termos e atualize o WhatsApp. Reenviar sem mudar nada dá o mesmo erro. Tudo sobre o erro 131026.
131047 — A janela de atendimento de 24 horas está fechada.
Descrição na tabela de códigos da MetaMore than 24 hours have passed since the recipient last replied to the sender number.
Por quê: Mensagem livre, sem template, enviada mais de 24 horas depois da última mensagem ou ligação do contato.
O que fazer: Envie um template aprovado. A janela reabre quando o contato responder. Tudo sobre o erro 131047.
131051 — O tipo de mensagem não é suportado.
Descrição na tabela de códigos da MetaUnsupported message type.
Por quê: O envio usou um tipo que a Cloud API não aceita. O mesmo código aparece em mensagens recebidas de um tipo que a API não sabe ler.
O que fazer: Use um dos tipos suportados (texto, mídia, localização, contatos, reação, interativo ou template).
131000 — Falha desconhecida do lado da Meta.
Descrição na tabela de códigos da MetaMessage failed to send due to an unknown error.
Por quê: A Meta não informa o motivo.
O que fazer: Tente de novo. Se persistir, a própria Meta orienta abrir um chamado no suporte dela.
Marketing não entregue
Templates de marketing que o WhatsApp segurou por regra do próprio WhatsApp ou do contato.
131049 — O WhatsApp segurou um template de marketing pelo limite por contato.
Descrição na tabela de códigos da MetaThis message was not delivered to maintain healthy ecosystem engagement.
Por quê: O contato atingiu o limite de templates de marketing que o WhatsApp entrega a ele, somando todas as empresas, ou a mesma mensagem foi reenviada antes de 24 horas.
O que fazer: Espere pelo menos 24 horas antes de reenviar. Reenviar antes só gera outro erro. Tudo sobre o erro 131049.
131050 — O contato parou de receber marketing da sua empresa.
Descrição na tabela de códigos da MetaUnable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business.
Por quê: A pessoa desativou as mensagens de marketing da empresa no WhatsApp.
O que fazer: Não reenvie para esse contato. A Meta avisa quando ele para ou volta a receber marketing pelo webhook user_preferences, que o CRPRO Hub ainda não transforma em evento.
130472 — O contato está num experimento da Meta que não recebe marketing.
Descrição na tabela de códigos da MetaMessage was not sent as part of an experiment.
Por quê: Uma porcentagem muito pequena de usuários não recebe template de marketing de nenhuma empresa, salvo com a janela de atendimento aberta.
O que fazer: Reenviar dá o mesmo erro, e a Meta não cobra a mensagem. Se precisar entregar, peça por outro canal que o contato mande uma mensagem e responda dentro da janela.
131063 — Template de marketing bloqueado na Cloud API por configuração da conta.
Por quê: A conta está configurada para não enviar templates de marketing pela Cloud API.
O que fazer: Envie pela Marketing Messages API ou desfaça a configuração na conta.
Limites de envio
Velocidade, mensagens para o mesmo contato e restrições do número.
131056 — Mensagens demais para o mesmo contato em pouco tempo.
Descrição na tabela de códigos da MetaToo many messages sent from the sender phone number to the same recipient phone number in a short period of time.
Por quê: O limite por par de números: cerca de uma mensagem a cada 6 segundos para o mesmo contato, com rajada curta de até 45. Loop de bot e campanha duplicada são os casos típicos.
O que fazer: Espere e tente de novo com recuo crescente. Mensagens para outros contatos continuam saindo normalmente.
130429 — O número passou da velocidade de envio permitida.
Descrição na tabela de códigos da MetaCloud API message throughput has been reached.
Por quê: Mais de 80 mensagens por segundo no número (até 1.000 para números de alto volume; 20 fixas em coexistência), contando entrada e saída.
O que fazer: Reduza a velocidade e tente de novo depois. Pelo CRPRO Hub, o limite de 60 envios por minuto por canal fica bem abaixo disso.
131048 — O número está com envio restrito por bloqueios e denúncias.
Descrição na tabela de códigos da MetaMessage failed to send because there are restrictions on how many messages can be sent from this phone number. This may be because too many previous messages were blocked or flagged as spam.
Por quê: Muitas mensagens anteriores do número foram bloqueadas ou marcadas como spam.
O que fazer: Confira a qualidade do número e dos templates no WhatsApp Manager e reduza os envios que geram bloqueio.
131064 — Envio limitado por violação na categoria de templates.
Por quê: A conta usou categorias de template em desacordo com as regras da Meta.
O que fazer: Revise as categorias dos templates. A restrição sai sozinha ao fim do período de punição.
131057 — O número está em manutenção.
Descrição na tabela de códigos da MetaBusiness Account is in maintenance mode
Por quê: Um caso documentado é o aumento automático da velocidade de envio, que deixa o número indisponível por até um minuto.
O que fazer: Espere alguns minutos e tente de novo.
Templates
O template enviado não bate com o template aprovado.
132000 — O número de variáveis enviadas não bate com o template.
Descrição na tabela de códigos da MetaThe number of variable parameter values included in the request did not match the number of variable parameters defined in the template.
Por quê: O template aprovado tem uma quantidade de variáveis e o envio mandou outra.
O que fazer: Mande um valor para cada variável do template, na quantidade exata.
132001 — O template não existe nesse idioma ou não está aprovado.
Descrição na tabela de códigos da MetaThe template does not exist in the specified language or the template has not been approved.
Por quê: Nome e idioma formam um par: o template aprovado em pt_BR não existe em en. Ou ele ainda não foi aprovado.
O que fazer: Confira o nome, o código do idioma e o status de aprovação do template.
132012 — As variáveis estão no formato errado para o template.
Descrição na tabela de códigos da MetaVariable parameter values formatted incorrectly.
Por quê: O template foi criado com variáveis nomeadas ({{first_name}}) e o envio mandou posicionais ({{1}}), ou o contrário. Sem formato declarado na criação, o padrão é posicional.
O que fazer: Envie no formato com que o template foi criado; em template com variáveis nomeadas, mande parameter_name.
132015 — O template foi pausado por baixa qualidade.
Descrição na tabela de códigos da MetaTemplate is paused due to low quality so it cannot be sent in a template message.
Por quê: Bloqueios, denúncias e baixa leitura derrubaram a nota do template.
O que fazer: Edite o template e envie de novo depois da aprovação. Um template pausado vezes demais é desativado de vez (132016), e aí só criando outro.
Mídia
Arquivo que a Meta não conseguiu processar.
131053 — A Meta não conseguiu processar a mídia da mensagem.
Descrição na tabela de códigos da MetaUnable to upload the media used in the message.
Por quê: O caso comum é o tipo do arquivo (MIME) não bater com o conteúdo, ou o formato não ser suportado.
O que fazer: Confira o tipo real do arquivo e os limites: imagem JPEG ou PNG até 5 MB, vídeo MP4 (H.264 e AAC) até 16 MB, áudio até 16 MB, documento até 100 MB, figurinha estática até 100 KB.
Conta, número e pagamento
Problemas da conta WhatsApp Business ou do número, não da mensagem.
131042 — Problema no meio de pagamento da conta.
Descrição na tabela de códigos da MetaThere was an error related to your payment method.
Por quê: Conta sem meio de pagamento válido, linha de crédito acima do limite ou inativa, conta suspensa, ou fuso horário e moeda não definidos.
O que fazer: Revise o faturamento da conta WhatsApp Business no gerenciador da Meta. Pelo CRPRO Hub, a conta e o pagamento são do cliente.
131031 — Conta restrita ou desativada, ou dado da requisição que não pôde ser verificado.
Por quê: Violação de política da plataforma, ou um dado da requisição que a Meta não conseguiu verificar, como o PIN de duas etapas errado.
O que fazer: Veja a situação da conta no WhatsApp Manager e, se for o caso, a orientação de aplicação de políticas da Meta.
368 — Conta restrita ou desativada por violação de política.
Descrição na tabela de códigos da MetaThe WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy.
Por quê: A Meta aplicou uma restrição à conta WhatsApp Business.
O que fazer: Veja o motivo no WhatsApp Manager e siga o processo de contestação da Meta.
133010 — O número não está registrado na Cloud API.
Descrição na tabela de códigos da MetaPhone number not registered on the WhatsApp Business Platform.
Por quê: O número foi conectado mas o registro não terminou, ou foi desfeito.
O que fazer: Registre o número de novo. No CRPRO Hub, isso é POST /api/v1/channels/{id}/register; a Meta limita a 10 tentativas por número em 72 horas.
Fontes
Fonte: códigos de erro da Cloud API, documentação da Meta conferida em 3 de outubro de 2026.