Erros da API Oficial do WhatsApp

Por que acontece

O WhatsApp separa conversa em duas situações. Enquanto o cliente responde, existe uma janela de 24 horas em que você escreve o que quiser. Passadas 24 horas do último envio dele, a janela fecha e só passa modelo aprovado pela Meta. A regra existe para que empresa não use o WhatsApp como canal de disparo unilateral — quem reabre a conversa é sempre o cliente, respondendo.

Como resolver

1. Envie um modelo aprovado (template) em vez de texto livre.
2. Quando o cliente responder ao modelo, a janela de 24 horas reabre e você volta a escrever livremente.
3. Se o modelo também falhar, confira se ele está aprovado e no idioma certo — aí o erro passa a ser 132001.

Por que acontece

Este erro é um guarda-chuva: a Meta não diz o motivo exato de propósito, para não expor informação sobre quem tem ou não WhatsApp. Por isso o diagnóstico é por eliminação, e quase sempre o problema está do outro lado.

Como resolver

1. Confirme o número em formato internacional, com código do país e DDD — no Brasil, atenção ao nono dígito.
2. Verifique se o número tem WhatsApp abrindo wa.me/55DDDNUMERO.
3. Teste o mesmo conteúdo para outro número seu: se funcionar, o problema é o destinatário, não a integração.
4. Se for isolado, o destinatário pode ter bloqueado seu número, estar com app desatualizado ou não ter aceitado os termos.

Por que acontece

Modelo é identificado pela dupla nome + idioma, não só pelo nome. Um modelo aprovado em pt_BR não atende uma chamada que pede pt_PT, e nome com maiúscula ou espaço não casa. Além disso, modelo em análise ou reprovado existe no painel mas não vale para envio.

Como resolver

1. Confira o nome exato no WhatsApp Manager — sem espaço, sem maiúscula, sem acento.
2. Confirme que o idioma pedido é o mesmo em que o modelo foi aprovado.
3. Verifique o status: em análise e reprovado não enviam.
4. Se o modelo foi criado agora, sincronize os modelos na plataforma antes de tentar.

Por que acontece

A Meta pontua a qualidade de cada número a partir de bloqueios e denúncias de quem recebe. Qualidade baixa reduz o teto de mensagens iniciadas por você. Não é punição por volume, é punição por reação ruim — mil mensagens bem recebidas não derrubam a nota; cem bloqueios derrubam.

Como resolver

1. Abra o WhatsApp Manager e veja o status de qualidade do número.
2. Reduza o volume de mensagens iniciadas por você até a nota se recuperar.
3. Pare de enviar para lista sem engajamento — é ela que gera bloqueio.
4. Revise o conteúdo dos modelos: mensagem que parece propaganda não pedida é a que mais derruba a nota.

Por que acontece

O teto é por destinatário, não por conta. A Meta limita quantas mensagens de marketing um mesmo usuário recebe num intervalo, de qualquer empresa. Reenviar na hora não adianta e ainda conta contra você.

Como resolver

1. Não reenvie imediatamente — a tentativa falha de novo.
2. Se o conteúdo couber, envie como modelo de Utilidade em vez de Marketing.
3. Espere pelo menos 24 horas antes de tentar de novo para o mesmo número.

Por que acontece

Diferente do 131049, aqui o limite é do par remetente-destinatário e vale para qualquer tipo de mensagem. Serve para conter automação em laço — o caso clássico é um fluxo que reenvia sozinho quando não recebe resposta.

Como resolver

1. Espere antes de tentar de novo para esse contato.
2. Envio para outros números segue normal — o bloqueio é só nesse par.
3. Revise se algum fluxo automático está reenviando em laço.

Por que acontece

A Meta seleciona uma fração pequena dos números — cerca de 1% — para medir o impacto de mensagens de marketing no ecossistema. Não é punição e não indica problema na sua conta. Enquanto durar, modelos de Marketing são bloqueados; os de Utilidade continuam passando.

Como resolver

1. Use modelos de Utilidade quando o conteúdo permitir.
2. Espere o cliente iniciar a conversa e responda dentro da janela de 24 horas.
3. Para contato inicial, use outro canal enquanto durar.

Por que acontece

O código cobre duas situações bem diferentes, e vale conferir a segunda antes de assumir a primeira. A restrição por política é consequência acumulada de reclamação e denúncia: a conta inteira para, e voltar depende de análise da Meta. Mas o mesmo código aparece quando um dado da requisição não bate com o cadastro — o caso mais comum é o PIN de verificação em duas etapas incorreto, que não tem nada de restrição e se resolve em minutos.

Como resolver

1. Primeiro confira o óbvio: o PIN de duas etapas enviado na requisição está correto?
2. Abra o Meta Business Manager e vá em Suporte para Empresas: se houver restrição, a notificação com o motivo está lá.
3. Leia a política citada e corrija o que a motivou antes de recorrer.
4. Responda à notificação pelo próprio painel — é o canal que a Meta acompanha.

Por que acontece

A API é cobrada por conversa, e a Meta suspende o envio quando a cobrança falha. Cartão válido não basta: emissor brasileiro costuma recusar cobrança internacional recorrente sem autorização prévia.

Como resolver

1. Confira os dados do cartão no Business Manager.
2. Tente o pagamento manual em Contas → Contas do WhatsApp → Configurações de pagamento.
3. Se recusar de novo, cadastre outro método e libere cobrança internacional no emissor.

Por que acontece

A API oficial não recebe tudo que o aplicativo recebe. Reação, figurinha animada, áudio temporário e formatos novos ficam de fora — a Meta libera na API depois do aplicativo, e alguns nunca chegam. Não é falha da integração.

Como resolver

1. Avise o contato que o formato não chega no atendimento.
2. Peça o reenvio como texto, imagem, áudio comum ou documento.

Por que acontece

A restrição é por país de DESTINO, e depende da categoria do seu negócio: a Meta permite conjuntos diferentes de países conforme o ramo declarado. Muita gente lê este erro como problema no cadastro da própria empresa — e às vezes é mesmo, porque a Meta não deduz o país pelo prefixo do número e usa o campo País do cadastro. Mas a causa oficial é a combinação categoria do negócio + país do destinatário.

Como resolver

1. Confira a Política de Mensagens da Meta para saber quais países a categoria do seu negócio alcança.
2. Verifique a categoria declarada da empresa no Business Manager: categoria errada restringe destinos sem motivo.
3. Confirme o campo País em Configurações do negócio → Informações da empresa, que a Meta usa como referência.

Por que acontece

O usuário pode desligar marketing de uma empresa direto no WhatsApp. A escolha é dele e vale até que ele mesmo mude. Insistir não entrega e ainda pesa contra a qualidade do seu número.

Como resolver

1. Não reenvie marketing para esse número.
2. Mensagens de Utilidade e resposta dentro da janela de 24 horas continuam valendo.
3. Marque o contato na sua base para não entrar em campanha de novo.

Por que acontece

Modelo com {{1}} e {{2}} exige exatamente dois valores, na ordem. Faltar, sobrar ou inverter derruba o envio inteiro — a Meta não preenche o que faltou nem descarta o que sobrou.

Como resolver

1. Confira quantas variáveis o modelo tem no WhatsApp Manager.
2. Envie um valor para cada, na ordem em que aparecem.
3. Variável vazia também conta: mande string vazia em vez de omitir.

Por que acontece

Adicionar o número no Business Manager não é o mesmo que registrá-lo na Cloud API. São dois passos, e o segundo — com o PIN de verificação em duas etapas — costuma ficar pela metade.

Como resolver

1. Conclua o registro do número na Cloud API antes de enviar.
2. Tenha o PIN de verificação em duas etapas à mão: ele é pedido no registro.
3. Se o número já esteve registrado em outro lugar, cancele o registro anterior primeiro.

Por que acontece

Token temporário da Meta dura 24 horas e serve só para teste. Integração em produção precisa de token de sistema, que não expira sozinho — mas é revogado se a senha do usuário mudar, se as permissões forem alteradas ou se o app sair do ar.

Como resolver

1. Gere um novo token de acesso.
2. Em produção, use token de usuário de sistema, não token temporário.
3. Confirme que o usuário de sistema tem as permissões do WhatsApp Business.

Por que acontece

Diferente dos limites por qualidade, este é técnico: mede mensagens por segundo, não por dia. É proteção de infraestrutura, e some sozinho quando o ritmo baixa.

Como resolver

1. Reduza a frequência de envio e tente de novo.
2. Distribua a campanha ao longo do tempo em vez de disparar tudo junto.
3. Implemente nova tentativa com espera crescente, não em laço imediato.

Por que acontece

A API recusa a requisição inteira em vez de assumir valor padrão. É proposital: mensagem enviada com campo faltando chegaria errada ao cliente, e isso é pior que não enviar.

Como resolver

1. Compare sua requisição com a referência do endpoint que está chamando.
2. Confira os campos básicos: messaging_product, to, type e o objeto do tipo escolhido.
3. A resposta de erro costuma nomear o campo que faltou — leia o corpo inteiro, não só o código.

Por que acontece

É o código genérico para falha interna da própria Meta. Quando aparece isolado, é instabilidade momentânea; quando aparece em série, costuma ser incidente do lado deles.

Como resolver

1. Tente de novo depois de alguns instantes.
2. Se persistir, verifique a página de status da plataforma antes de mexer na integração.
3. Se for logo após reconectar o número, refaça a integração: desconecte e conecte de novo.

Por que acontece

A qualidade é medida por modelo, não só por número. Um modelo que gera bloqueio é pausado sozinho, e os outros continuam funcionando — por isso o problema costuma ser o texto daquele modelo, não a conta.

Como resolver

1. Edite o modelo para melhorar a qualidade e reenvie para aprovação.
2. Enquanto isso, use outro modelo aprovado para o mesmo fim.
3. Se o mesmo modelo for pausado de novo, o texto é o problema, não a frequência.

Por que acontece

Indisponibilidade declarada do lado da Meta. Não há o que corrigir na sua integração — mexer nela durante um incidente costuma criar problema novo.

Como resolver

1. Consulte a página de status da plataforma antes de qualquer coisa.
2. Espere e tente de novo; não refaça a integração durante um incidente.
3. Segure a fila de envio em vez de deixar cada mensagem falhar sozinha.