Erros da API do WhatsApp Business: Códigos, Causas e Soluções

Sua campanha de Black Friday está agendada. 40.000 contatos, template aprovado, tudo na fila.

Você clica em enviar e o painel fica vermelho. 131047. 132001. 131048.

Nenhuma explicação em português claro, só uma parede de códigos de cinco dígitos e uma campanha que não sai do lugar.

Se você já opera a API do WhatsApp Business, o canal oficial da Meta para falar com clientes em escala, há mais de algumas semanas, já encontrou esses códigos. Como a Meta controla o pipeline inteiro, toda falha volta como um número.

O canal é valioso demais para você perder uma campanha por causa de um código que não reconhece:

• Mais de 3 bilhões de pessoas no WhatsApp
• Taxas de abertura chegando a 98%

A boa notícia: os erros da API do WhatsApp são bem mais previsíveis do que parecem.

• Quase todo erro tem origem em cinco causas raiz
• A maioria leva menos de 10 minutos para resolver, desde que você saiba em qual grupo está

Este guia cobre todos os códigos de erro que você provavelmente vai encontrar, o que realmente causa cada um e exatamente como corrigir.

O que são erros da API do WhatsApp Business?

Um erro da API do WhatsApp Business é uma resposta codificada que a Meta devolve quando uma solicitação sua (enviar uma mensagem, submeter um template, registrar um número) não pode ser concluída.

Diferente do aplicativo WhatsApp Business, em que uma mensagem falha apenas exibe o ícone de relógio, a API informa com precisão o que deu errado. Isso é um recurso, não um defeito. O problema é que as mensagens de erro da Meta são escritas para desenvolvedores, e não para profissionais de marketing. Por isso "Re-engagement message" não deixa óbvio que "sua janela de 24 horas expirou".

Todo erro que você vai encontrar pertence a um destes cinco grupos:

• Erros de conta e configuração: seu número, WABA ou verificação do negócio não está em um estado que permita envio
• Erros de template: o template não existe, foi rejeitado, foi pausado ou suas variáveis não batem
• Erros de entrega: a mensagem era válida, mas não conseguiu chegar àquele destinatário específico
• Erros de limite de envio: você está enviando mais rápido ou mais volume do que sua conta permite no momento
• Erros de integração: seu token, webhook ou ferramenta conectada quebrou a cadeia

Saber o grupo já resolve uns 80% do caminho até a solução. O código resolve o resto.

Como ler uma resposta de erro da API do WhatsApp

Toda solicitação com falha retorna um objeto JSON parecido com este:

{
  "error": {
    "message": "(#131047) Re-engagement message",
    "type": "OAuthException",
    "code": 131047,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Message failed to send because more than 24 hours have passed since the customer last replied to this number."
    },
    "fbtrace_id": "AbCdEfGhIjK"
  }
}

Quatro nomenclaturas que você precisa saber:

• code: o número de cinco dígitos. É o que você pesquisa e o que organiza tudo o que vem abaixo.
• message: o título curto da Meta. Costuma ser críptico ("Re-engagement message" sozinho não diz quase nada).
• error_data.details: a explicação de verdade, em texto corrido. A maioria das pessoas pula direto para o código e perde esse campo, que normalmente nomeia o problema exato.
• fbtrace_id: um ID único daquela solicitação específica. Sempre inclua isso ao abrir um chamado de suporte. Sem ele, a Meta não consegue rastrear o que aconteceu.

Onde conferir os erros:

• Na AiSensy: abra a campanha e vá em Delivery Logs (registros de entrega). Você vê o código de erro de cada contato que falhou.
• Na Meta: abra o WhatsApp Manager para verificar qualidade dos templates, problemas na conta ou restrições no número de telefone.

Observação importante: se o mesmo erro aparece para todo mundo, o problema provavelmente está na conta ou no template enviado.

Se apenas alguns contatos são afetados, é mais provável que seja um problema de entrega.

Leia mais: Qual a melhor ferramenta de disparo em massa no WhatsApp

Códigos de Erro da API do WhatsApp Business: Tabela de Referência Completa

Aqui está a lista completa dos códigos que você realmente vai encontrar, agrupados por tipo. Salve esta seção nos favoritos, é o caminho mais rápido do código até a causa.

Erros de Autorização e de Permissão

Estes são erros de token ou credencial que o BSP (provedor de soluções do WhatsApp) resolve pelo usuário. Um profissional de marketing na sua plataforma nunca encosta neles.

Esses erros são gerenciados pelo seu BSP (como a AiSensy), então acione o suporte caso apareçam.

Erros de Throttling e Limite de Envio

Este erro significa que você está enviando rápido demais, ou volume demais para o seu tier atual.

Erros de Envio e Entrega de Mensagens

A solicitação era válida, mas a mensagem não chegou ao destinatário.

Template Errors

Na Cloud API, que praticamente todas as empresas usam hoje, os equivalentes são 131047 e 131026, respectivamente.

Erros de Onboarding e Configuração de conta

Estes travam você antes mesmo do primeiro envio. (Se você ainda não começou sua solicitação, siga primeiro nosso guia passo a passo da API do WhatsApp Business. Vários desses erros só fazem sentido quando você sabe em que ponto do fluxo está.)

Erro "número já registrado"

Costuma acontecer quando o número já está ativo no WhatsApp ou no aplicativo WhatsApp Business.

Um número de telefone só pode estar conectado a um produto WhatsApp por vez, então você precisa removê-lo ou migrá-lo antes de registrá-lo na API.

Códigos relacionados que podem aparecer nesse processo:

Importante: se o número está em um chip que você ainda usa no WhatsApp pessoal, não faça isso.

Use um número novo para a API. Depois que um número entra na API, você não consegue mais usá-lo no aplicativo WhatsApp do seu celular.

Verificação do Negócio e Rejeição do Nome de Exibição

São duas checagens diferentes quando o assunto é verificação do negócio e rejeição do nome de exibição.

Verificação do Negócio

A Meta confere se sua empresa está legalmente registrada. A verificação pode falhar quando os dados do Business Manager não batem exatamente com os documentos.

Por exemplo, "Têxtil Souza Comércio Ltda." e "Têxtil Souza" podem ser tratados como nomes diferentes.

Como corrigir:

• Deixe a razão social idêntica à dos documentos.
• Envie um documento que mostre nome da empresa, endereço e CNPJ.
• Garanta que seu site exiba os mesmos dados da empresa.
• Se for rejeitado duas vezes, fale com o Suporte da Meta em vez de reenviar o mesmo documento.

Rejeição do Nome de Exibição

O nome de exibição é o nome que os clientes veem no WhatsApp.

A Meta pode rejeitar nomes que:

• Não correspondem à sua empresa ou marca
• São genéricos demais, como "Melhores Ofertas"
• Incluem URLs, telefones, emojis ou ofertas
• Usam uma marca registrada cuja titularidade você não consegue comprovar

A opção mais segura é a razão social registrada ou um nome de marca claramente ligado ao seu site.

Erro relacionado:

Erros de Template de Mensagem do WhatsApp

Erros de template podem travar uma campanha inteira, o que os torna um dos problemas mais comuns da API do WhatsApp.

Por que a Meta rejeita templates

A maioria das rejeições acontece porque a categoria escolhida estava errada.

Qualquer mensagem com conteúdo promocional é tratada como Template de Marketing. Por exemplo, uma atualização de entrega que divulga produtos novos pode ser rejeitada se for enviada como template de utilidade.

Estes são os motivos mais comuns de rejeição:

Três dicas práticas que melhoram bastante a taxa de aprovação:

• Não comece a mensagem com uma variável. Escreva "Olá {{1}}" em vez de abrir direto com "{{1}}".
• Coloque valores de amostra de verdade. A Meta revisa a prévia final da mensagem, não só o formato do template.
• Envie os templates com antecedência. Em períodos de pico, a aprovação demora mais, então submeta pelo menos 48 horas antes da campanha.

Templates Pausados, Desativados ou Sinalizados

Um template aprovado não fica aprovado para sempre. A Meta pontua continuamente cada template com base na reação dos destinatários.

132015, template pausado. A qualidade do seu template caiu para baixa, normalmente por taxa de bloqueio e denúncia. A pausa é temporária:

• Primeira pausa: 3 horas
• Segunda pausa: 6 horas
• Terceira pausa: 24 horas

Templates pausados voltam sozinhos. Use o período de pausa para melhorar a qualidade da lista de inscritos e reduzir a frequência de envio.

O erro 132016 significa que o template foi desativado em definitivo. Crie um novo template com conteúdo diferente.

Para evitar isso:

• Envie apenas para opt-ins recentes
• Limite a frequência de marketing
• Segmente seu público
• Monitore a qualidade dos templates toda semana

Correções rápidas de template

 Se você ainda está definindo qual formato usar em cada situação, vale conferir os tipos de mensagens template do WhatsApp e a biblioteca de templates prontos.  

Erros de Entrega de Mensagens no WhatsApp

Estes aparecem quando a mensagem em si está certa, mas o destinatário ou o contexto não está.

Erro 131047: Mensagem de Reengajamento Necessária

O erro 131047 significa que a janela de atendimento de 24 horas fechou.

A janela abre quando um cliente manda mensagem para você. Durante essas 24 horas, você pode enviar respostas comuns, imagens ou documentos.

Depois que a janela fecha, só templates aprovados podem ser enviados.

Como corrigir:

• Verifique quando o cliente mandou mensagem pela última vez
• Se a janela estiver fechada, envie um template aprovado
• Assim que o cliente responder, a janela de 24 horas abre de novo

Como evitar:

• Confira o cronômetro da janela antes de responder
• Crie templates para follow-ups com prazo curto
• Use lembretes automáticos antes de a janela fechar

Erros relacionados:

No Brasil, o opt-out normalmente chega como uma resposta SAIR, então garanta que sua base trate essa palavra como pedido de descadastro imediato.

Erro 131026: Mensagem não Entregável

Isso significa que o WhatsApp aceitou a mensagem, mas não conseguiu entregar a mensagem.

Motivos comuns:

• O número não está ativo no WhatsApp
• O código do país ou o formato do número está incorreto
• O destinatário usa uma versão desatualizada do WhatsApp
• O aparelho dele não suporta aquele tipo de mensagem
• A conta está restrita
• O envio de mensagens é limitado naquela região

Como corrigir:

• Use o formato internacional completo, sem [+], espaços ou zeros à esquerda
• Valide os números antes de subir a lista de contatos
• Remova números que falham de forma recorrente
• Se muitos contatos apresentam esse erro, confira primeiro a formatação da sua lista

Um número brasileiro deve ficar assim: 5511987654321.

Limites de Envio e Limites de Mensagens

São controles de vazão, não punições. Existem para impedir que uma conta comprometida ou mal configurada inunde os usuários.

Tiers de mensagens do WhatsApp explicados

Toda conta do WhatsApp Business fica em um tier de mensagens que limita quantos clientes únicos você pode iniciar conversa a cada 24 horas corridas. Respostas a clientes que falaram com você primeiro não entram nessa conta.

Duas atualizações importantes:

• Os limites de mensagens agora valem no nível do Portfólio de Negócios, então todos os números conectados compartilham o tier mais alto disponível.
• A Meta revisa os aumentos de tier a cada poucas horas, então contas elegíveis podem subir no mesmo dia.

Como Aumentar seu Limite de Mensagens

A Meta costuma aumentar seu limite quando:

• Você usa pelo menos 50% do limite atual em 7 dias
• A qualidade da sua conta e dos seus templates se mantém alta

Veja também como planejar disparos em massa sem estourar seus limites.

Para melhorar suas chances:

• Conclua a Verificação do Negócio
• Use o limite disponível de forma consistente
• Mantenha sua classificação de qualidade verde
• Aumente o volume de mensagens de forma gradual
• Mantenha um uso estável ao longo dos 7 dias

Escolher o melhor horário para enviar seus disparos ajuda a manter o engajamento alto enquanto você sobe de tier.

Códigos de Erro de Limite de Envio

Classificação de Qualidade e Restrições de Conta

A classificação de qualidade é a métrica que, silenciosamente, determina todo o resto: seu tier, se os templates continuam ativos e se o seu número sobrevive.

Qualidade verde, amarela e vermelha explicada

A Meta pontua cada número de telefone pela reação dos destinatários às suas mensagens em uma janela corrida de 7 dias.

Bloqueios e denúncias derrubam a nota. Engajamento e respostas sustentam.

Uma classificação vermelha não causa rebaixamento imediato, mas se persistir, templates podem ser desativados e o número pode ser restringido.

Causas comuns:

• Enviar para usuários sem opt-in claro
• Enviar para listas antigas ou inativas
• Disparar promoções com frequência excessiva
• Enviar mensagens irrelevantes em massa
• Enviar conteúdo que o usuário não pediu para receber

A qualidade depende muito mais da reação do usuário do que do volume de mensagens. Mensagens relevantes para uma base com opt-in mantêm sua nota saudável, enquanto uma segmentação ruim leva a nota para o vermelho rapidamente. Se o assunto é conformidade, vale entender como uma crise de conformidade no WhatsApp Business se instala.  

O que Fazer se seu Número for Restringido

Os erros 368 ou 131031 significam que o WhatsApp interrompeu os envios da sua conta. Veja como desbanir seu número do WhatsApp Business.

O que fazer:

• Confira o aviso de restrição no Business Manager
• Pare de enviar mensagens daquele número
• Revise o motivo exato no painel do seu BSP
• Envie um recurso pelo WhatsApp Manager
• Explique o que aconteceu e o que você mudou
• Anexe provas, como formulários de opt-in ou uma lista de contatos higienizada

Evite recursos genéricos do tipo "por favor, restaure minha conta". Provas claras aumentam suas chances.

Não crie um número novo para continuar a mesma prática. A Meta pode restringir esse número também.

Sinais de Alerta

Fique de olho em:

• Queda nas taxas de entrega
• Qualidade saindo do verde para o amarelo
• Templates sendo pausados
• Taxas de leitura caindo
• Aumentos de tier esperados que não acontecem

Corrija a qualidade da lista e a frequência de envio antes de a restrição piorar.

Erros de Mídia e de Anexos

Erros de mídia normalmente acontecem porque o arquivo é grande demais, não é suportado ou está inacessível.

Problemas comuns:

• O arquivo ultrapassa o limite de tamanho do WhatsApp
• O formato ou o tipo real do arquivo não é suportado
• A URL da mídia é privada, está quebrada ou não é HTTPS
• O media ID enviado expirou

Erros relacionados:

Para arquivos usados com frequência, suba a mídia uma vez e reaproveite o media ID em vez de depender de links externos.

Erros da API do WhatsApp: Dicas Rápidas de Diagnóstico

Quando uma mensagem falhar, confira estes pontos nesta ordem:

• Leia os detalhes completos do erro, não só o código
• Veja se o erro afeta todos os contatos ou apenas alguns
• Verifique se sua conta está restrita
• Revise sua classificação de qualidade
• Confirme nome, idioma, status e variáveis do template
• Cheque se a janela de 24 horas está aberta
• Valide o formato do número do destinatário
• Verifique seu token de acesso e a configuração do webhook

Ainda travado?

Salve o fbtrace_id, o horário e a resposta de erro completa antes de acionar o suporte.

Como a AiSensy Ajuda a Evitar Erros da API do WhatsApp

A AiSensy ajuda a prevenir os problemas mais comuns da API do WhatsApp antes que eles atinjam suas campanhas.

• Verifica templates antes do envio para aprovação
• Avisa quando a qualidade cai
• Mostra erros de entrega de forma clara
• Cuida das novas tentativas e dos limites de envio
• Exibe o cronômetro da janela de 24 horas
• Apoia a verificação e a configuração da conta

Explore todos os recursos da plataforma, veja casos de uso reais ou confira os estudos de caso.

Comece grátis e configure sua API do WhatsApp Business com menos erros.

Conclusão

Os erros da API do WhatsApp parecem técnicos, mas a maioria fica simples assim que você entende o que cada código quer dizer.

Para evitar problemas recorrentes, foque em quatro coisas: colete opt-ins de verdade, segmente seu público, não exagere na frequência e monitore sua classificação de qualidade.

Faça isso de forma consistente e os erros da API do WhatsApp passam a ser exceção, não rotina.

Perguntas frequentes

Links rápidos

• Como solicitar a API do WhatsApp Business
• Tipos de mensagens template do WhatsApp
• Plano Básico ou Plano Pro: qual escolher
• Chatbot no WhatsApp: o que é e como criar
• Agente de IA no WhatsApp vs chatbot
• Caixa de entrada multiagente para WhatsApp
• Anúncios no WhatsApp: guia completo
• Casos de uso da API do WhatsApp Business
• Biblioteca de templates de mensagem do WhatsApp
• (EN Version) WhatsApp Business API Errors: Causes & Fixes