Experimente o Omnifox grátis 7 dias grátis. Sem cartão de crédito.
Guias

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.

September 05, 2026
Erros da API do WhatsApp: 131031, 131047, 130429 e o que fazer com 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 failed e 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:

    1. Verificação de empresa pendente ou rejeitada no portfólio da Meta. Ocorre muito com portfólios recém-criados.
    2. Pagamento com falha: o cartão foi recusado e a conta ficou bloqueada até a regularização.
    3. 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:

    1. Consulte o estado do número e a saúde do canal (health_status). Se a conta está bloqueada, nada mais importa.
    2. Veja se o erro veio na resposta do envio ou no webhook de status.
    3. Se for 131047, use modelo. Se for 131009, confira as variáveis. Se for 190, reconecte.
    4. Se for 130429, reduza a velocidade. Se for 131048/131056 ou queda de qualidade, pause campanhas e revise opt-in.
    5. 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.

    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.

    Markdown suportado. HTML é removido.

    Leia mais

    Fale conosco no WhatsApp