Erros da API do WhatsApp: o que significam e como resolver
Tomou um código de erro no envio pela Cloud API? Aqui está a lista dos erros mais comuns — o que cada um significa e como corrigir. Na WhatsFlow B2B, boa parte disso a plataforma já trata sozinha (reenvio inteligente, classificação de erro).
Guia técnico • Provedora oficial da Meta • Comece grátis
Por que a API do WhatsApp retorna código de erro?
Quando você envia uma mensagem pela Cloud API do WhatsApp, a Meta responde com um código de erro se algo impede a entrega: fora da janela de 24h, número inválido, template não aprovado, limite de qualidade, problema de mídia ou de pagamento. Cada código aponta uma causa diferente — e a correção muda conforme o motivo.
De forma geral, os erros se dividem em recuperáveis (vale reenviar depois — ex.: 131047 fora da janela, 131026 indisponível no momento) e permanentes (não adianta reenviar o mesmo conteúdo — ex.: número inválido, template reprovado). Na WhatsFlow, a plataforma classifica o erro e reenfileira automaticamente o que é recuperável, deixando só o permanente como falha. Abaixo, o que fazer em cada caso.
Os 3 grupos de erro
Saber o grupo já diz o que fazer.
Recuperável
A entrega falhou agora, mas pode dar certo depois (janela 24h, indisponibilidade, experimento da Meta). Reenviar mais tarde resolve.
Transitório / limite
Sobrecarga ou rate limit. Espera um pouco e tenta de novo, com backoff — não martela.
Permanente
Número inválido, opt-out, template reprovado, mídia inválida. Reenviar o mesmo não adianta — corrija a causa.
Códigos de erro da API do WhatsApp
Erro 131047 — o que significa?
“Re-engagement message”: passou mais de 24 horas desde a última mensagem do cliente, então você não pode mandar texto livre — só uma mensagem de template aprovado. Correção: envie por template (HSM). Recuperável: reenviar por template reabre a conversa.
Erro 131026 — mensagem não entregue (message undeliverable)
A mensagem não pôde ser entregue agora: o número pode não ter WhatsApp, não aceitar sua mensagem, ou estar temporariamente indisponível. Verifique se o número é válido e tem WhatsApp. Muitas vezes é recuperável (reenviar depois); se o número não existe, é permanente.
Erro 131049 — a Meta optou por não entregar
A Meta limitou a entrega para preservar a saúde do ecossistema (ex.: excesso de marketing para aquele usuário no período). Reduza a frequência de marketing e respeite o opt-in. Costuma ser recuperável mais tarde.
Erro 131048 — limite de spam (qualidade) atingido
Seu número atingiu o limite por qualidade baixa/denúncias. Pare de disparar, melhore o opt-in e o conteúdo, e aguarde a qualidade se recuperar. Ligado ao bloqueio por spam.
Erro 131053 / 131052 — erro de mídia
131053 = falha ao subir sua mídia (formato/tamanho inválido); 131052 = falha ao baixar a mídia do usuário. Verifique formato e tamanho do arquivo. Geralmente permanente até corrigir a mídia.
Erro 131021 — destinatário não pode ser o remetente
Você tentou enviar para o próprio número que está enviando. Use um destinatário diferente. Permanente.
Erro 130472 — usuário faz parte de um experimento
A Meta segurou a entrega porque o usuário está num experimento dela. Nada de errado com você — costuma normalizar depois. Recuperável.
Erro 131042 — problema de elegibilidade/pagamento do negócio
Há um problema de billing/elegibilidade na sua conta business (ex.: forma de pagamento no Business Manager). Acerte o pagamento no business correto. Recuperável quando resolvido.
Erro 131056 — muitas mensagens para o mesmo par
(pair rate limit) Você mandou mensagens demais para o mesmo número em pouco tempo. Espace os envios. Espera e reenvia.
Erros 132000 / 132001 / 132005 / 132007 / 132012 — template
132000 = número de parâmetros não bate; 132001 = template não existe/não aprovado nesta WABA ou idioma; 132005 = texto ficou longo demais; 132007 = viola política de formato/caracteres; 132012 = formato do parâmetro incorreto. Correção: ajuste ou reaprove o template. Permanente até corrigir.
Erro 132016 — template desabilitado
O template foi pausado/reprovado por qualidade. Crie um novo template dentro das políticas ou aguarde a reavaliação. Permanente até resolver.
Erro 190 / 401 — token inválido
O token de acesso expirou ou é inválido. Renove/reconecte a conta. Na WhatsFlow isso é gerenciado pela plataforma.
A WhatsFlow trata esses erros sozinha?
Em boa parte, sim. A plataforma classifica cada erro em recuperável, transitório ou permanente e reenfileira automaticamente o que vale reenviar (respeitando o rate limit), deixando só o permanente como falha real — você não precisa ficar caçando código.
Pare de caçar código de erro
Na WhatsFlow B2B a plataforma classifica e reenvia sozinha o que é recuperável, na API oficial da Meta. Comece grátis.