Erros Comuns da API do WhatsApp: Causas e Soluções

Este artigo reúne os erros mais frequentes retornados pela API do WhatsApp Business (Cloud API/Meta) em nossa plataforma, explicando por que eles ocorrem e como reduzir sua incidência.

This message was not delivered to maintain healthy ecosystem engagement

Esse erro indica que a Meta decidiu não entregar a mensagem para preservar a qualidade do ecossistema do WhatsApp. Na prática, costuma ocorrer em envios de templates de marketing, especialmente quando o destinatário já recebeu muitas mensagens de marketing, não interage com esse tipo de conteúdo ou está sujeito a limites por usuário.

A Meta aplica limites por usuário para templates de marketing com o objetivo de reduzir fadiga, spam e baixa relevância. Esses limites podem variar conforme o engajamento recente do usuário.

Causa: A Meta identificou que o destinatário pode não estar engajado (baixa taxa de abertura/resposta) ou que o remetente está enviando volume alto para números com baixo engajamento histórico.
Mitigação: Não reenvie a mesma mensagem imediatamente. Aguarde pelo menos 24 horas antes de tentar novamente ou use intervalos progressivamente maiores. Reenvios imediatos tendem a falhar enquanto o limite estiver ativo.

User's number is part of an experiment

Esse erro ocorre quando o número do destinatário faz parte de um experimento conduzido pela Meta/WhatsApp. Nesses casos, a mensagem não é enviada como parte do experimento, e isso não indica necessariamente problema no template, na conta, no número do remetente ou na integração.

Causa: A Meta roda testes A/B internos de entrega em uma amostra de números aleatórios, testando mudanças de infraestrutura ou políticas de entrega.
Mitigação: Não é controlável pelo remetente. É temporário — geralmente basta tentar reenviar a mensagem após algum tempo. Não indica erro na sua implementação.

Message undeliverable

Esse erro indica que a mensagem não pôde ser entregue ao destinatário. É um erro amplo: a Meta pode não informar a causa exata por motivos de privacidade e política. Entre as causas documentadas estão número que não usa WhatsApp, cliente que bloqueou a empresa, país restrito, aceite pendente dos termos da Meta ou versão antiga do aplicativo.

Causas possíveis: número não tem WhatsApp instalado/ativo, usuário bloqueou o número business, problemas de conectividade do destinatário, ou o número está fora da janela de 24h sem template aprovado.
Mitigação: Valide números antes do envio, garanta uso de template correto para primeira mensagem fora da janela de sessão.

Media upload error

Causas possíveis: arquivo excede o limite de tamanho (varia por tipo: imagem 5MB, vídeo 16MB, documento 100MB), formato de mídia não suportado, URL de mídia inacessível (se usando link), ou timeout no upload.
Mitigação: Valide tipo e tamanho do arquivo antes do envio, use formatos suportados oficialmente (JPEG/PNG para imagem, MP4 para vídeo, etc.), teste se a URL está publicamente acessível e sem redirecionamentos.

Param text cannot have new-line/tab characters or more than 4 consecutive spaces

Causa: Os parâmetros de variáveis em templates ({{1}}, {{2}} etc.) têm restrições de formatação — não aceitam \n, \t, ou sequências de mais de 4 espaços consecutivos.
Mitigação: Sanitize os valores das variáveis antes de enviá-los, removendo/substituindo quebras de linha e normalizando espaços múltiplos.

Parameter of type text is missing text value

Causa: O payload enviado declara um parâmetro do tipo text (dentro de components do template) mas não inclui o campo text com o valor, ou envia string vazia/nula.
Mitigação: Valide no seu código, antes do envio, que todo parâmetro do tipo text possui um valor não vazio associado. Adicione uma checagem de payload (schema validation) antes de chamar a API para evitar esse erro em produção.

Body: Length of the parameters and the template text is `<NUM>`, which exceeds the allowed length of 1024

Causa: A soma do texto fixo do template com os valores das variáveis substituídas excede o limite de 1024 caracteres imposto pela Meta para o corpo da mensagem.
Mitigação: Trunque ou resuma valores de variáveis longas (ex: descrições de produtos, nomes extensos) antes de enviar, calcule o tamanho total esperado (template + parâmetros) no seu código e valide contra o limite antes da chamada à API, retornando um erro amigável internamente caso exceda.