Erro 131062 no WhatsApp Business API: o que significa e como resolver

Se você recebeu o erro 131062 no WhatsApp Business API e quer saber o que significa, a resposta curta é: sua tentativa de envio foi recusada ou bloqueada pela Meta, e o código sozinho não conta a história toda. Ele faz parte da família de erros 131xxx, que a Cloud API usa para sinalizar problemas de mensageria e entrega. Para resolver de verdade, você precisa ler o retorno completo da API, e não apenas o número.

Esse é o erro que mais confunde quem está começando na API oficial. A pessoa vê só o número no log, procura na internet e não acha uma definição fechada. Isso acontece porque a Meta muda e reorganiza a documentação de códigos com frequência, e alguns códigos aparecem em situações específicas de conta, número ou template. Por isso a abordagem correta não é decorar o significado, é aprender a extrair a causa do próprio erro.

Onde está a resposta de verdade: dentro do JSON

Quando a Cloud API recusa um envio, ela devolve um objeto de erro estruturado. O código (por exemplo, 131062) é só uma etiqueta. A explicação está nos campos que vêm junto:

• code: o número do erro.
• title: um título curto que descreve a categoria do problema.
• message: uma frase legível sobre o que aconteceu.
• error_data.details: o campo mais valioso. Aqui a Meta costuma detalhar a causa exata, em texto.

Na prática, quando um cliente nos procura dizendo que o envio falhou com um código da faixa 131, a primeira coisa que a gente pede é o JSON inteiro, não o número solto. O campo details quase sempre já entrega o motivo: janela fechada, falta de opt-in, limite atingido, número restrito. Sem ele, você fica adivinhando.

Regra prática: nunca trate um erro 131xxx pelo número isolado. Leia o title e o error_data.details antes de qualquer coisa.

As causas reais por trás de erros de envio na faixa 131xxx

Os bloqueios de envio que você vê nessa faixa quase sempre caem em um destes grupos. Vale checar um por um, na ordem de probabilidade.

1. Você está fora da janela de 24 horas

Depois que o cliente te manda uma mensagem, você tem 24 horas para responder com texto livre. Passou disso, só com template aprovado. Se seu sistema tentar mandar uma mensagem de conversa (sessão) fora dessa janela, a API recusa. É o erro de reengajamento, e é de longe a causa número um de envios travados que a gente vê no dia a dia.

Solução: fora da janela, envie um template das categorias marketing, utilidade ou autenticação, já aprovado pela Meta. Quando o cliente responder, a janela reabre.

2. Falta de opt-in ou envio percebido como spam

A API oficial não é lista fria. Para iniciar conversa (fora da janela de 24h) você precisa de consentimento do cliente, o opt-in. Quando muita gente bloqueia seu número, marca como spam ou você dispara em massa para quem não pediu, a Meta reduz sua capacidade de envio e pode recusar mensagens até o comportamento normalizar.

Solução: colete opt-in de forma clara, respeite quem pediu para sair e evite disparos genéricos para bases não engajadas.

3. Qualidade do número em queda

A Meta classifica cada número como qualidade Alta (verde), Média (amarela) ou Baixa (vermelha). Quando a qualidade cai para vermelho, o número entra em observação e pode ter limites reduzidos ou envios bloqueados temporariamente. Na prática, o que mais derruba a qualidade é conteúdo que gera bloqueio: promoção agressiva, frequência alta e mensagens que o cliente não esperava.

Solução: acompanhe a qualidade no Gerenciador do WhatsApp, reduza o volume por alguns dias e melhore a relevância das mensagens. A qualidade se recupera com bom comportamento ao longo do tempo.

4. Limite diário de conversas atingido

Existem limites diários de conversas iniciadas pela empresa, os chamados tiers. Eles aumentam conforme volume, qualidade e verificação da empresa. Se você estourou o limite do dia, novos envios ativos são recusados até o próximo ciclo.

Solução: verifique sua empresa no Gerenciador de Negócios (Business Verification) e mantenha qualidade alta. É assim que o limite sobe. Se não sabe qual é o seu patamar atual, o próprio painel mostra, e os valores mudam com o tempo.

5. Problema com o template usado

Se o envio depende de um modelo de mensagem, o template precisa estar aprovado e ativo. Template rejeitado, pausado por qualidade baixa ou desabilitado não sai. Quando um cliente chega com template travado, quase sempre é por parâmetro faltando, variável fora do formato ou conteúdo que fere a política da Meta.

Solução: confira o status do template no Gerenciador, corrija o conteúdo e reenvie para aprovação. Cheque também se o número e o formato das variáveis batem com o que você está mandando na chamada.

6. Conta ou pagamento com pendência

Se a conta da empresa tem restrição, ou se o método de pagamento cadastrado na Meta está com problema, os envios podem parar. Vale lembrar de como funciona a cobrança: quem paga as conversas é o próprio cliente, direto para a Meta, com o cartão cadastrado na conta dele.

Segundo a covercut, BSP oficial do WhatsApp, a nossa mensalidade cobre plataforma, conexão do número pelo fluxo oficial da Meta e suporte, mas a cobrança por conversa é feita direto entre o cliente e a Meta. Nós não intermediamos nem repassamos esse valor. Então, se o problema for pagamento, ele é resolvido na conta da Meta, não no BSP.

Passo a passo para diagnosticar o 131062

1. Copie o JSON completo do erro, com title, message e error_data.details.
2. Leia o details. Ele costuma dizer em texto o que a Meta bloqueou.
3. Verifique se você está dentro ou fora da janela de 24 horas para aquele contato.
4. Se for envio ativo, confirme se há opt-in e se o template está aprovado e ativo.
5. Abra o Gerenciador do WhatsApp e cheque a qualidade do número e o limite de conversas.
6. Confira o status da conta e o método de pagamento na conta da Meta.

Na maioria dos casos, o motivo aparece já no segundo passo. Quando não aparece, é sinal de que o problema é de conta ou de limite, e não da mensagem em si.

Como evitar que o erro volte

Erro de envio na API oficial raramente é aleatório. Ele é consequência de comportamento. Mantenha opt-in de verdade, mande o que o cliente espera receber, respeite a janela de 24 horas e use templates dentro da política. Complete a verificação da empresa para subir o limite de conversas. E monitore a qualidade do número toda semana, porque a queda começa antes de o envio travar.

Se você opera na coexistência (o mesmo número no app WhatsApp Business e na API oficial ao mesmo tempo, sem perder histórico), vale um cuidado extra: mensagens ativas continuam seguindo as regras da API, então disparos fora da janela precisam de template mesmo que você também use o app no celular.

Ficou preso no erro depois de checar os seis pontos acima? Junte o JSON completo do retorno e fale com o suporte do seu BSP. Com o error_data.details em mãos, a causa costuma sair em minutos.

Perguntas frequentes

O que significa o erro 131062 no WhatsApp Business API?

É um retorno da Cloud API indicando que o envio foi recusado ou bloqueado. O código faz parte da faixa 131xxx, ligada a mensageria e entrega. Para saber a causa exata, leia o campo error_data.details do JSON do erro, que é onde a Meta descreve o motivo real.

Por que minha mensagem foi bloqueada mesmo com o número ativo?

Número ativo não garante envio. As causas mais comuns são estar fora da janela de 24 horas sem template aprovado, falta de opt-in, qualidade do número em queda, limite diário de conversas atingido ou template rejeitado. Cheque esses pontos antes de suspeitar de falha técnica.

Esse erro tem a ver com pagamento das mensagens?

Pode ter, se o método de pagamento na conta da Meta estiver com pendência. A cobrança das conversas é feita direto entre o cliente e a Meta, no cartão cadastrado pelo próprio cliente. O BSP cobra apenas a mensalidade do serviço e não repassa o valor das conversas.

Como faço para o envio voltar a funcionar?

Identifique a causa pelo JSON do erro e trate o ponto correspondente: envie template aprovado se estiver fora da janela, garanta opt-in, melhore a qualidade do número, aguarde o próximo ciclo se estourou o limite ou ajuste o template. Depois, teste o envio novamente.

Preciso apagar minha conta do app para usar a API e evitar esse erro?

Não. Com a coexistência, você conecta o mesmo número à API oficial sem desinstalar o app nem perder o histórico. Isso não tem relação com o erro de envio, que depende de janela, opt-in, qualidade, limites e status do template.