Erros da API do WhatsApp: 131031, 131047, 130429 e o que fazer com cada um
Guia dos códigos de erro mais comuns da API do WhatsApp (131031 conta bloqueada, 131047 janela de 24 h, 130429 limite, 131049) e como resolver cada um.
Neste artigo
Os erros da API do WhatsApp chegam em dois lugares diferentes, e é por isso que confundem tanto. Alguns aparecem na hora, como resposta ao envio: você tenta mandar a mensagem e a Meta devolve um código. Outros só chegam depois, pelo webhook de status: o envio foi aceito, mas a mensagem não foi entregue, e o motivo vem em uma notificação separada. Quem procura o 131031 na resposta do envio não vai encontrar.
Este guia reúne os códigos que mais aparecem no atendimento de empresas brasileiras na Cloud API (131031, 131047, 130429, 131049 e alguns vizinhos), com o que cada um significa, a causa habitual e a ação prática. Não é a lista completa da documentação da Meta; é a lista do que de fato acontece.
Também explicamos por que o campo health_status da conta é a fonte da verdade quando você quer saber se o número pode enviar, antes de gastar tempo tentando.
Onde cada erro aparece
Há três canais por onde a Meta informa um problema:
- Resposta síncrona ao envio: você chama a API para enviar e recebe um erro na hora. Aqui aparecem 131047, 130429, 131009, 190 e 131026, entre outros.
- Webhook de status: a mensagem foi aceita (você recebeu um ID), mas depois chega uma notificação com status
failede o código do motivo. O 131031 (conta empresarial bloqueada) e o 131049 (limite de marketing por usuário) chegam principalmente por aqui. - Saúde da conta (
health_status): um campo consultável na API que resume se o número, o portfólio e o modelo estão aptos a enviar, com o motivo quando não estão.
Em uma plataforma como o Omnifox, esses três sinais são consolidados em um painel de saúde do canal (qualidade, estado do número e nível de mensageria), para que o atendente não precise ler webhook.
Tabela de códigos: significado, causa e ação
| Código | Significado | Causa habitual | O que fazer |
|---|---|---|---|
| 131031 | Business Account locked (conta empresarial bloqueada) | Verificação pendente, pagamento com falha ou violação de política | Ver o motivo no Gerenciador do WhatsApp; regularizar verificação ou cartão; se for política, solicitar revisão |
| 131047 | Re-engagement (fora da janela de 24 horas) | Tentativa de enviar texto livre para quem não escreveu nas últimas 24 h | Enviar um modelo aprovado para reabrir a conversa |
| 130429 | Rate limit (limite de taxa) | Muitas requisições em pouco tempo ou pico de envio | Reduzir a velocidade, enfileirar e reenviar com intervalo |
| 131049 | Limite de mensagens de marketing por usuário | O destinatário já recebeu muitos modelos de marketing de várias empresas ("healthy ecosystem") | Não reenviar imediatamente; segmentar melhor e tentar em outro momento |
| 131026 | Mensagem não entregável | Número sem WhatsApp, cliente bloqueou a empresa ou não aceitou os termos | Marcar o contato e não insistir |
| 131048 / 131056 | Limite por taxa de spam | Muitos envios com baixa resposta ou denúncias | Pausar campanhas, revisar opt-in e a qualidade do modelo |
| 190 | Token expirado ou inválido | Token de acesso vencido, permissão revogada, senha alterada | Reconectar o canal pelo fluxo oficial |
| 131009 | Parâmetro de modelo inválido | Número de variáveis diferente do modelo, formato errado | Corrigir as variáveis e reenviar |
| 141006 | Método de pagamento | Cartão recusado ou cobrança pendente | Atualizar o cartão na conta do WhatsApp Business |
| 141010 | Empresa sem verificar | Portfólio sem verificação de empresa | Concluir a verificação na Meta |
131031: o erro que não aparece onde você procura
O 131031 é o mais mal diagnosticado, porque a API aceita o envio normalmente. Você chama, recebe um ID de mensagem, tudo parece bem; minutos depois, o webhook devolve status failed com o código 131031 e a mensagem "Business Account locked".
Uma notificação de status típica fica assim (simplificada):
{
"statuses": [{
"id": "wamid.HBgN...",
"status": "failed",
"errors": [{
"code": 131031,
"title": "Business Account locked",
"message": "Account has been locked",
"error_data": {
"details": "Business account is locked. Check the WhatsApp Manager for details."
}
}]
}]
}
Os três motivos mais comuns por trás dele, em ordem de frequência no suporte:
- Verificação de empresa pendente ou rejeitada no portfólio da Meta. Ocorre muito com portfólios recém-criados.
- Pagamento com falha: o cartão foi recusado e a conta ficou bloqueada até a regularização.
- Violação de política apontada pela Meta, com pedido de revisão dentro do Gerenciador do WhatsApp.
Em todos os casos, a ação começa no Gerenciador do WhatsApp, não na plataforma: o motivo está lá. O checklist antes de conectar a API evita a maior parte dessas situações.
131047: a janela de 24 horas em uma linha
O 131047 é o mais simples de resolver e o que mais aparece. Significa: o cliente não escreveu nas últimas 24 horas, então você não pode mandar texto livre; precisa usar um modelo aprovado.
Exemplo: uma loja de móveis em Curitiba quer avisar que o sofá chegou. O cliente comprou há uma semana e não escreveu desde então. O atendente digita "Seu sofá chegou!", e recebe 131047. A solução é um modelo de utilidade:
Olá, Fernanda! Seu pedido 4821 da Casa & Conforto chegou ao nosso depósito. Podemos entregar na terça (16/09) entre 9h e 13h. Responda 1 para confirmar ou 2 para escolher outro dia.
Quando o cliente responde, a janela reabre e a conversa segue livre. O funcionamento completo está em a janela de 24 horas do WhatsApp: modelos vs mensagens de sessão.
130429 vs 131048/131056: limite de velocidade vs limite de spam
Os três são "limites", mas dizem coisas diferentes:
- 130429 é técnico: você está fazendo requisições rápido demais. Enfileire e reenvie com intervalo. Não tem relação com qualidade.
- 131048 e 131056 são de comportamento: a Meta reduziu sua capacidade de envio porque a taxa de resposta caiu ou as denúncias subiram. Reenviar com intervalo não resolve; é preciso pausar, revisar a lista e o conteúdo.
Se você vê 131048/131056, olhe também o nível de mensageria e a qualidade do número no painel. É comum que venham acompanhados de uma queda de nível.
131049: o limite que não é seu
O 131049 é diferente de todos os outros porque a causa não está no seu número. A Meta limita quantas mensagens de marketing cada usuário recebe de todas as empresas em um período. Se o seu cliente já recebeu vários modelos de marketing de outras marcas, o seu pode não ser entregue, mesmo com opt-in e qualidade alta.
O que fazer:
- Não reenviar em seguida; a chance de repetir o erro é alta.
- Priorizar modelos de utilidade (confirmação, entrega, lembrete) sobre os de marketing sempre que o conteúdo permitir.
- Segmentar por quem interagiu recentemente e reduzir a frequência.
- Registrar o contato como "não entregue por limite de marketing" e tentar em outra janela.
O planejamento de campanhas em torno desses limites está em limites de mensagens de marketing no WhatsApp 2026.
Rotina de diagnóstico em 5 passos
Quando "as mensagens não estão saindo", siga esta ordem em vez de tentar reenviar:
- Consulte o estado do número e a saúde do canal (
health_status). Se a conta está bloqueada, nada mais importa. - Veja se o erro veio na resposta do envio ou no webhook de status.
- Se for 131047, use modelo. Se for 131009, confira as variáveis. Se for 190, reconecte.
- Se for 130429, reduza a velocidade. Se for 131048/131056 ou queda de qualidade, pause campanhas e revise opt-in.
- Se for 131031, 141006 ou 141010, vá ao Gerenciador do WhatsApp e resolva verificação ou pagamento.
Perguntas frequentes
O que significa o erro 131031 na API do WhatsApp?
Significa que a conta empresarial do WhatsApp está bloqueada, geralmente por verificação pendente, pagamento com falha ou violação de política. Ele chega pelo webhook de status, não na resposta do envio, e o motivo específico fica no Gerenciador do WhatsApp.
Como resolver o erro 131047?
Enviando um modelo aprovado em vez de texto livre. O 131047 indica que o cliente não escreveu nas últimas 24 horas, e fora dessa janela só modelos podem iniciar a conversa.
O erro 130429 é um bloqueio?
Não. O 130429 é um limite de taxa técnico: você enviou requisições rápido demais. Basta reduzir a velocidade e reenviar. Já os códigos 131048 e 131056 indicam limite por spam e exigem revisão de lista e conteúdo.
Por que recebo 131049 se meu cliente deu opt-in?
Porque o limite é do usuário, não do seu número: a Meta restringe quantas mensagens de marketing cada pessoa recebe de todas as empresas. Priorize modelos de utilidade e tente em outro momento.
Veja o erro antes do cliente perceber
A diferença entre uma equipe que apaga incêndio e uma que atende com tranquilidade está em enxergar o estado do número, o nível e a qualidade em um único painel, com o erro traduzido para português. É assim que o Omnifox mostra a saúde do canal. Comece um teste grátis de 7 dias em /register e conecte seu número pela API oficial.
Pronto para testar no seu negócio?
Reúna WhatsApp, Instagram, Messenger, e-mail e chamadas em uma só caixa de entrada e deixe a IA dar a primeira resposta. Configure hoje mesmo.
7 dias grátis. Sem cartão de crédito.
Leia mais
-

CRM para SMS marketing: como segmentar e medir de verdade
-

Como responder quando voce nao tem o produto disponivel (sem perder o cliente)
-

Taxa de resolucao de tickets: o que e e como medir direito
-

Como integrar o Google Ads ao seu CRM conversacional
-

O melhor CRM de WhatsApp em 2026 (comparativo)
-

O que é VoIP e como funciona a voz sobre IP
-
Métricas do TikTok que realmente importam para vender
-

10 erros ao colocar um chat no seu site (e como corrigir hoje)
Comentários (0)
Ainda não há comentários. Seja o primeiro a compartilhar.
Deixe um comentário
Seu email nunca é publicado. Os comentários são moderados antes de aparecer.