Debugging na WhatsApp cloud API: como resolver os erros 131049 e 130472

Quem cria integracoes e chatbots usando a WhatsApp Cloud API da Meta ja passou por este susto: de repente, mensagens de envio ativo comecam a falhar e o primeiro pensamento e que o servidor caiu, o webhook quebrou ou o token de acesso expirou.

Passei exatamente por isso ao acompanhar fluxos de atendimento automatizado. As mensagens pararam de ser entregues, os clientes comecaram a reclamar e, ao abrir os logs da aplicacao, os retornos HTTP indicavam codigos de erro da Meta: 131049 e 130472.

Depois de analisar detalhadamente as respostas JSON e cruzar com os limites da plataforma, percebi que a aplicacao estava perfeita. O problema era inteiramente do lado da Meta (o que chamamos de restricao de upstream).

Abaixo mostro a anatomia desses dois erros, o que cada payload significa e quais sao as melhores alternativas praticas para manter as mensagens fluindo.

Comparativo rapido entre os erros 131049 e 130472#

A tabela abaixo resume a diferenca fundamental entre as duas falhas:

O erro 131049: Protecao antispam no destinatario#

O erro 131049 acontece quando sua aplicacao tenta disparar uma mensagem ativa usando um template da categoria Marketing.

O payload de resposta da meta#

Ao enviar a requisicao HTTP POST para a API do WhatsApp, a Meta recusa o envio e devolve este objeto JSON:

{
  "error": {
    "message": "(#131049) User marketing template message limits exceeded.",
    "type": "OAuthException",
    "code": 131049,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "The recipient has received too many marketing messages recently. For more details, see official Meta documentation."
    },
    "fbtrace_id": "ArX9_J8k2LpM5N7q"
  }
}

O que realmente esta acontecendo#

Nao e problema de saldo, de chave de API ou de sintaxe no seu JSON.

A Meta monitora quantas mensagens comerciais cada usuario do aplicativo WhatsApp recebe por dia de qualquer empresa. Se o usuario recebeu varios disparos promocionais nas ultimas horas, a Meta bloqueia novos templates de marketing para aquele numero especifico para evitar que a pessoa sinta que o aplicativo virou uma caixa de spam.

Ou seja: o bloqueio esta no destinatario, nao no seu sistema.

Como contornar o erro 131049#

1. Trocar para templates da categoria Utilidade (Utility): Se o contato precisa ser feito imediatamente e o conteudo tem carater transacional (aviso de pedido, codigo de seguranca, atualizacao de cadastro), utilize um template aprovado como Utilidade. Esses templates nao entram no teto de marketing e passam direto pela validacao da Meta.
2. Pausar envios para o destinatario: Nao adianta colocar um loop tentando reenviar o mesmo template a cada 30 segundos. Adicione uma regra na sua fila de disparo para suspender envios promocionais para aquele numero por 12 a 24 horas.
3. Incentivar o contato inicial pelo cliente: Se o cliente mandar qualquer mensagem para o seu numero, uma janela oficial de conversa de 24 horas e aberta. Dentro dessa janela, voce pode responder com mensagens livres sem depender de templates de marketing.

O erro 130472: O experimento aleatorio de 1% da meta#

Este erro costuma gerar mais confusao, porque o bloqueio nao depende do cliente que recebe a mensagem, mas sim do seu proprio numero comercial.

O payload de resposta da meta#

{
  "error": {
    "message": "(#130472) Meta experiment restriction applied to marketing templates.",
    "type": "OAuthException",
    "code": 130472,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "This phone number is part of a controlled experiment to evaluate user experience with marketing templates."
    },
    "fbtrace_id": "Z8y7X6w5V4u3T2s1"
  }
}

O que realmente esta acontecendo#

A Meta realiza testes A/B continuos na infraestrutura do WhatsApp Cloud API. Cerca de 1% das contas comerciais no mundo sao selecionadas aleatoriamente para fazerem parte de experimentos internos de volume e engajamento.

Quando o seu numero cai nesse grupo:

• O status do seu numero no painel da Meta continua verde e saudavel.
• Os seus cartoes e saldos continuam ativos.
• Os seus templates continuam como aprovados.

Ainda assim, qualquer tentativa de enviar templates de marketing e rejeitada com o codigo 130472.

Nao existe um botao no painel nem uma rota de API para pedir a saida desse teste. A Meta remove a restricao automaticamente assim que o ciclo de coleta de dados do experimento termina.

Como contornar o erro 130472#

1. Reestruturar o contato inicial para Utilidade: Durante o periodo do experimento, evite iniciar conversas com modelos de marketing. Configure o seu bot para iniciar conversas usando notificacoes transacionais legitimas.
2. Usar canais alternativos para disparar a janela de 24 horas: Envie um SMS ou e-mail com o link direto para o seu WhatsApp (https://wa.me/seunúmero?text=Quero+saber+mais). Quando o cliente clica e manda a mensagem, a conversa passa a ser iniciada pelo usuario (user-initiated). Isso abre a janela de 24 horas para trocar mensagens de texto e midia sem passar pela trava de marketing.

Estrategias para manter a comunicacao ativa sem travar nos limites da meta#

Entender que os erros 131049 e 130472 nascem fora da sua aplicacao evita horas perdidas revisando codigos perfeitamente funcionais.

Para construir um sistema mais resiliente:

1. Trate esses codigos no seu webhook ou worker: Em vez de marcar a mensagem como erro generico no banco de dados, capture explicitamente os codigos 131049 e 130472.
2. Avise sua equipe de atendimento de forma clara: Quando esses codigos forem identificados, exiba uma mensagem informativa no seu painel interno explicando que a Meta pausou temporariamente o envio daquele modelo.
3. Mantenha templates de Utilidade aprovados de reserva: Tenha sempre modelos aprovados nas categorias de Autenticacao e Utilidade prontos para uso em notificacoes essenciais.

Dessa forma, sua integracao lida com as regras e mudancas da Meta sem interromper os servicos essenciais do seu atendimento.

Veja também

Desenvolvimento Como integrar o IndexNow: indexação instantânea para sites, SaaS e APIs

Desenvolvimento Mapeando caminhos absolutos no PHP: como resolvi a resolução de paths no meu servidor

Desenvolvimento Atualizando o Vite no Laravel: do inotify do kernel ao manifest.json

Este post está licenciado sob CC BY-NC.