Erros da API do WhatsApp: 131047, 131026, 131049 e mais

Os erros 131047, 131026 e 131049 são respostas da Meta, não do provedor: 131047 significa que você tentou mandar mensagem livre com a janela de 24 horas fechada, 131026 significa que o número de destino não tem WhatsApp ativo, e 131049 significa que aquela pessoa já recebeu marketing demais, somando todas as empresas, e a Meta segurou a sua. Cada código diz de quem é a regra e o que fazer, e é isso que este dicionário organiza. Nenhum deles é cobrado, porque a Meta só cobra mensagem entregue.

Resposta curta: como ler um erro da Meta

Todo envio pela API oficial termina de um de três jeitos. A Meta aceita e devolve um id de mensagem. A Meta recusa na hora, com um código de erro na resposta. Ou a Meta aceita e desiste depois, e a falha chega por webhook, num status failed com o mesmo tipo de código. Webhook é o aviso que a Meta manda ao servidor do provedor quando algo acontece com uma mensagem.

Para ler o código, faça três perguntas, nesta ordem:

1. De quem é a regra? Da Meta como plataforma, do destinatário, do seu número ou da sua conta. Isso decide se existe algo para consertar do seu lado.
2. Reenviar adianta? Na maioria dos códigos deste artigo, não. Reenviar às cegas repete a falha e, em dois casos, piora a situação.
3. O que muda o resultado? Um template aprovado, uma espera de 24 horas, tirar o contato do público, cadastrar um cartão, reconectar o número. Cada código tem uma saída só.

Pela API do Frame Conexa a recusa chega como um 502 com o objeto de erro da Meta anexado em graph. É o mesmo objeto que a Meta devolve, sem tradução, porque o código é a pista mais útil que existe:

{
  "error": "a Meta recusou o envio",
  "graph": {
    "code": 131049,
    "message": "This message was not delivered to maintain healthy ecosystem engagement."
  }
}

Quando a falha vem depois do aceite, ela chega pelo seu webhook de saída, no evento messages, dentro de statuses[].errors. O painel lê os dois caminhos e mostra o motivo ao lado do destinatário. Os limites da própria API do Frame Conexa, que são de requisição e não de mensagem, estão em erros e limites e não se confundem com os códigos daqui.

Erros de janela e template

São os erros de quem tentou mandar a coisa certa no momento errado, ou a coisa errada no formato certo. A regra por trás deles é a mais básica da API oficial do WhatsApp: a empresa só escreve o que quiser dentro de uma janela aberta pelo cliente. Fora dela, só template, que é a mensagem com texto fixo aprovada pela Meta antes de sair.

131047: fora da janela de 24 horas

A descrição oficial é que mais de 24 horas se passaram desde a última resposta do destinatário. Você tentou uma mensagem livre, de texto ou mídia, e a janela de 24 horas estava fechada. A Meta recusa na hora. A mensagem não sai e não é cobrada.

A janela é do WhatsApp, não do provedor, e não abre por insistência. Reenviar dá 131047 de novo. A saída é um template aprovado pela Meta: de utilidade para retomar um atendimento, de marketing para uma oferta. Se a pessoa responder ao template, a janela abre e a conversa livre volta a valer.

Há uma janela maior num caso só. Quem chega por um anúncio Click-to-WhatsApp e é respondido em até 24 horas abre uma janela de 72 horas em que qualquer mensagem é gratuita. Em coexistência, quando a resposta sai pelo app do celular, a Meta não manda ao provedor a confirmação de cobrança dessa janela, então o painel aplica a regra documentada de boa-fé. O erro 131047 continua sendo a resposta da Meta quando ela considera a janela fechada, seja de 24 ou de 72 horas.

Importante: a partir de 01/10/2026 a Meta passa a cobrar por mensagem as respostas livres dentro da janela de 24 horas e os templates de utilidade enviados dentro dela. A regra da janela não muda. O que muda é que "dentro da janela" deixa de significar "grátis". Confira o rate card oficial da Meta ao publicar preços.

132000 e 132001: template com variáveis erradas ou inexistente no idioma

Os códigos que começam com 132 são de template mal montado. O 132000 diz que a quantidade de variáveis enviadas não é a que a Meta aprovou: o template tem dois espaços para preencher e o envio mandou três, ou um. O 132001 diz que o template não existe no idioma pedido, ou não está aprovado nele. Um template aprovado em português e enviado como en_US cai aqui.

Os dois são erros da integração, e por isso são os únicos deste artigo em que reenviar resolve, desde que o envio seja corrigido antes. Template pausado pela Meta por qualidade baixa também é rejeitado na hora, e a saída é outra: rever o template, não o envio.

Erros do destinatário

Aqui o seu número está bem e o seu template está bem. O problema está na outra ponta, e o provedor não tem como saber antes de tentar. É por isso que toda campanha para lista fria termina com uma fatia de falhas deste grupo, e por isso a fatia não é sinal de avaria.

131026: não é usuário do WhatsApp ou não aceitou os termos

A Meta não conseguiu entregar porque o número não tem WhatsApp, ou a pessoa ainda não aceitou os termos novos do app, ou usa uma versão antiga demais. Os três casos chegam com o mesmo código, e nenhum deles se resolve do seu lado.

A ação é tirar esses contatos do público. Reenviar dá o mesmo resultado, e uma lista com muitos 131026 é uma lista velha: números que trocaram de dono ou nunca tiveram WhatsApp. Se a lista veio de uma importação, vale checar a origem antes da próxima campanha.

131049: limite de marketing por pessoa, espere 24 horas

A mensagem oficial é que a mensagem não foi entregue para manter o engajamento saudável do ecossistema. Por trás dela está um limite que a Meta aplica por destinatário: quantos templates de marketing uma mesma pessoa pode receber num período, somando todas as empresas que falam com ela. O número não é divulgado. A Meta descreve o limite como dinâmico, baseado em quanto aquela pessoa tem lido as mensagens de marketing que recebe.

Esse limite não é do seu número nem do provedor, e nenhum painel consegue prever o erro, porque ninguém sabe quantas mensagens de marketing aquela pessoa recebeu de outras empresas hoje. A orientação da Meta é esperar pelo menos 24 horas antes de tentar de novo. Reenviar antes disso pode prolongar o bloqueio por mais 24 horas. Templates de utilidade e de autenticação não entram nessa conta, e mensagens dentro de uma janela aberta pela própria pessoa também não.

O limite de mensagens da API explica como esse limite por pessoa convive com a capacidade do seu número, que é outro limite, também da Meta, e que esse sim aparece no painel antes do envio.

131050: a pessoa pediu para não receber marketing

O destinatário desativou, no próprio WhatsApp, o recebimento de mensagens de marketing da sua empresa. A Meta recusa a entrega e informa a preferência dele. Não há o que reenviar: a decisão é da pessoa, e insistir por outro caminho contraria a política de mensagens da Meta.

No Frame Conexa o contato sai do público automaticamente quando esse código chega. A Meta também avisa a preferência por um webhook próprio, user_preferences, que o painel assina, então a saída do público acontece mesmo quando a pessoa muda a preferência sem que você tenha enviado nada. Quem volta a aceitar marketing volta ao público sozinho. Só a supressão feita à mão pela sua equipe não é desfeita por webhook.

130472: experimento da Meta, não reenvie

A descrição oficial é que a mensagem não foi enviada como parte de um experimento. A Meta mantém um grupo pequeno de usuários que não recebe mensagem de marketing de empresa com quem nunca conversou. É um teste dela, sem prazo divulgado para acabar e sem como a empresa sair.

Reenviar falha de novo. Essa pessoa só recebe se mandar mensagem primeiro, o que abre a janela de 24 horas e tira o envio da categoria de marketing frio. Na prática, vale tirar do público de campanha e deixar que ela chegue por outro canal, como um anúncio ou um link.

Erros do número e da conta

Neste grupo o problema está do seu lado da mesa: no ritmo de envio, na saúde do número, no pagamento da conta ou na autorização que o número deu ao provedor. São os únicos erros do artigo que pedem uma ação sua antes do próximo disparo.

130429: velocidade demais

A Meta recusou por excesso de envios por segundo. O teto por número é dela: um número em coexistência, que continua no app do celular, fica fixo em 20 mensagens por segundo, e um número exclusivo da API começa mais alto e sobe sozinho conforme o uso. O Frame Conexa serializa os envios por número dentro desse teto e refaz o envio uma vez em caso de 130429, então o código só chega até você quando a tentativa automática também falhou.

A ação é reenviar com ritmo menor. Um primo dele é o 131056, que limita quantas mensagens um número manda para a mesma pessoa em pouco tempo: a saída é esperar alguns minutos antes de mandar de novo para aquele contato.

131048: restrição por qualidade, a Meta pediu para parar

A Meta detectou taxa de spam alta nesse número e segurou os envios. É a restrição por qualidade: os destinatários bloquearam, denunciaram ou marcaram o número como indesejado nos últimos dias, e a Meta responde reduzindo o que ele pode mandar. Desde outubro de 2025 a qualidade baixa não rebaixa mais a capacidade que o número já conquistou. O que ela faz é impedir a subida, pausar templates de qualidade baixa e ligar esta restrição.

Aqui reenviar é o pior movimento possível, porque cada tentativa recusada reforça o sinal. No Frame Conexa uma campanha que recebe 131048 é pausada sozinha. A ação é reduzir o ritmo, revisar o público, tirar quem não deu permissão e só então retomar. O artigo sobre WhatsApp Business bloqueado mostra o que acontece quando esse sinal é ignorado por tempo demais.

131042: problema no pagamento da conta na Meta

O envio falhou porque a conta do WhatsApp Business na Meta está sem método de pagamento válido: cartão não cadastrado, limite de crédito estourado ou linha de faturamento inativa. É o erro que mais surpreende quem acabou de conectar, porque o número está verde, o template está aprovado e mesmo assim nada sai.

A Meta cobra o cliente direto pelas mensagens de template entregues, e como Tech Provider o Frame Conexa não cadastra o pagamento pelo cliente: quem cadastra o cartão é você, no seu próprio Business Manager. O painel confere a saúde da conta antes de criar uma campanha, avisa quando ela está bloqueada por pagamento e entrega o link do Business Manager para resolver. Depois de cadastrado o cartão, o próximo envio sai sem reconectar nada.

133010: número não registrado

O número não está registrado na plataforma da Meta. Esse código é raro em coexistência, porque o próprio app do celular já registrou o número. Ele aparece em número novo, exclusivo da API, quando o passo de registro não aconteceu ou foi desfeito. No Frame Conexa o registro faz parte da conexão do número novo, e a saída para um 133010 é reconectar o número em Instâncias.

190: autorização revogada, reconectar

O 190 não é sobre a mensagem. É sobre o token, a credencial que o seu número entregou ao provedor quando você autorizou a conexão. Ela expirou ou foi revogada: alguém removeu o parceiro no Business Manager, a conta foi reestruturada, ou a autorização caiu por outro motivo do lado da Meta. Enquanto ela não for refeita, nenhum envio sai e nenhum inbound chega.

Ao ver um 190 o Frame Conexa marca a instância como desconectada, emite o evento instance_status com disconnected no seu webhook de saída, e a API passa a responder 409 com o pedido de reconectar. A reconexão é o mesmo fluxo da primeira vez, o Embedded Signup, a partir do painel. O histórico de conversas e o público ficam onde estavam.

Tabela-resumo: código, de quem é, o que fazer

Vale a leitura por coluna. A coluna "de quem é" mostra que só quatro linhas são suas. A coluna "reenviar" mostra que, das treze, reenviar sem mudar nada resolve nenhuma.

Como o painel do Frame Conexa mostra cada motivo

O painel não mostra o código sozinho. Cada falha aparece com três pedaços: um rótulo curto, uma explicação que diz de quem é a recusa, e uma ação executável na tela. O 131049 aparece como "limite da Meta por pessoa", com a explicação de que o limite vale por destinatário e não pelo seu número, e a ação "espere pelo menos 24 horas". O 130472 aparece como "experimento da Meta". O 131047, como "janela fechada", com a ação "envie um template aprovado".

Esse dicionário nasceu de uma campanha real. Em setembro de 2026, um envio em massa para 250 contatos frios terminou com 36 falhas, todas 131026, 130472 ou 131049. A tela mostrava o número do código e um texto que falava em "limite de marketing por destinatário" sem dizer que o limite era da Meta. A suspeita natural de quem paga por número é de que o limite seja do provedor, e a tela dava margem para isso. O dicionário existe para tirar essa dúvida antes de ela virar um chamado de suporte.

Três comportamentos automáticos completam o dicionário:

• 131050 suprime o contato. Quem pediu para não receber sai do público na hora, e a supressão automática é desfeita se a pessoa voltar a aceitar. A supressão manual da sua equipe nunca é desfeita por webhook.
• 131048 pausa a campanha. A Meta mandou parar, e o painel para. Retomar é uma ação sua, depois de rever público e ritmo.
• 190 desconecta a instância. O status muda para desconectado no painel, no webhook de saída e na API, num evento só por transição. Reconectar religa tudo.

Para o card "Falhas por motivo", que agrupa a campanha inteira por código, o rodapé lembra que a Meta só cobra mensagem entregue. Para quem não conhece a API, "falha" soa como dinheiro perdido, e não é.

Existe ainda um quarto estado, que não tem código da Meta: o resultado incerto. Quando a Meta não responde a tempo, o envio pode ter saído ou não. A API devolve o erro com ambiguous: true, e a instrução é não reenviar às cegas, porque a mensagem pode duplicar. No painel esses envios aparecem como "incertos", e o botão "Reenviar incertas" confere antes de repetir. Quem integra pela API pode mandar um Idempotency-Key no envio, e a repetição da mesma chave devolve o resultado da primeira tentativa em vez de criar um segundo envio.

Para quem trata o webhook de saída em código, a decisão por código cabe em poucas linhas. O que importa é separar o que sai do público, o que espera e o que pede ação humana:

function decidir(codigo) {
  switch (Number(codigo)) {
    case 131026:
    case 130472:
    case 131050:
      return 'remover-do-publico';
    case 131049:
      return 'tentar-depois-de-24h';
    case 130429:
    case 131056:
      return 'tentar-mais-devagar';
    case 131047:
      return 'usar-template';
    case 131048:
    case 131042:
    case 133010:
    case 190:
      return 'acao-humana';
    default:
      return `erro ${codigo}`;
  }
}

Código desconhecido continua saindo como o próprio código, nunca como um "erro genérico". Um código sem tradução ainda é uma pista: dá para procurar na lista oficial de códigos de erro da Meta.

Próximo passo

Se você opera pela API, a referência de status HTTP, rate limits e do resultado incerto está em erros e limites. Se você opera pelo painel, o motivo de cada falha já aparece ao lado do destinatário, com a ação certa. Para conectar um número e ver isso funcionando, veja os planos por número.