A API Oficial do WhatsApp, gerenciada pela Meta, é uma solução robusta para empresas que desejam escalar o atendimento e o envio de mensagens. Porém, durante o uso, podem surgir erros de retorno que impedem o envio ou a entrega das mensagens.
Neste guia, reunimos os principais erros da API do WhatsApp, explicando o que cada um significa e quais ações tomar para corrigir ou evitar o problema.
1. Message Undeliverable (Mensagem não entregue) #
Esse retorno indica que a mensagem não chegou ao destinatário. As causas mais comuns incluem:
- Número inexistente ou desativado
- Contato bloqueou sua empresa
- Usuário não aceitou os Termos de Serviço do WhatsApp
- Versão do aplicativo desatualizada
Como agir:
Confirme se o número está correto, ativo e se o contato já interagiu anteriormente com sua empresa.
2. Rate Limit Exceeded (Limite de envio excedido) #
Ocorre quando a conta ultrapassa o volume permitido de mensagens em um determinado período. Esse limite varia conforme o nível de qualidade (tier) atribuído pela Meta à sua conta.
Como agir:
Aguarde o período de resfriamento antes de novos envios e mantenha boas práticas para melhorar sua reputação de envio.
3. Spam Rate Limit Reached (Limite de spam atingido) #
Esse erro aparece quando muitos destinatários bloqueiam ou denunciam mensagens como spam, reduzindo drasticamente o limite de envio do número.
Como agir:
Revise a estratégia de disparo, garanta consentimento (opt-in) e evite mensagens excessivas ou irrelevantes.
4. Invalid Phone Number (Número inválido) #
Indica que o número informado não está registrado no WhatsApp.
Como agir:
Verifique se o número contém código do país + DDD corretamente e confirme o contato por outro canal, se necessário.
5. Access Denied (Acesso negado) #
Esse erro está relacionado a permissões da conta, token expirado ou problemas no Facebook Business Manager.
Como agir:
Revise o token de acesso, as permissões da API e o status da conta de negócios vinculada.
6. Media Loading Error (Erro ao carregar mídia) #
Ocorre ao tentar enviar arquivos em formatos não suportados ou fora dos padrões exigidos pela API.
Como agir:
Confira se o tipo de mídia (imagem, vídeo, áudio ou documento) está dentro das especificações oficiais do WhatsApp.
7. Paused Model (Template pausado por baixa qualidade) #
O template foi temporariamente suspenso devido a baixa taxa de engajamento ou denúncias.
Como agir:
Exclua o template pausado, revise o conteúdo e crie um novo com uma abordagem mais clara e relevante.
8. Model Disabled (Template desativado permanentemente) #
Após múltiplas pausas por baixa qualidade, o template é desativado de forma definitiva.
Como agir:
Crie um novo modelo e inclua opções de opt-out, permitindo que o usuário escolha não receber esse tipo de mensagem.
9. The user number is part of an experiment (Número faz parte de experimento da Meta) #
Alguns usuários (cerca de 1%) participam de testes da Meta que bloqueiam mensagens de marketing.
Como agir:
Teste o envio com templates do tipo Utility ou incentive o contato a iniciar a conversa manualmente.
10. This message was not delivered to maintain healthy ecosystem engagement. (Mensagem bloqueada para manter engajamento saudável) #
Esse erro está ligado a uma regra recente da Meta que limita o envio de mensagens de marketing consecutivas sem resposta.
Exemplo:
Se duas mensagens de marketing forem enviadas sem interação do usuário, novos envios não serão entregues até o encerramento da janela.
Como agir:
Aguarde interação do contato antes de novos disparos ou alterne estratégias de comunicação.
11. Something Went Wrong (Falha genérica no envio) #
Erro genérico que pode estar associado a instabilidades temporárias, sessão ativa ou falhas momentâneas da Meta.
Como agir:
Atualize a página, aguarde alguns minutos e tente novamente.
Boas práticas para evitar erros na API do WhatsApp #
- Trabalhe sempre com opt-in válido
- Evite excesso de mensagens promocionais
- Monitore a qualidade da conta regularmente
- Utilize templates claros, objetivos e relevantes
- Respeite os limites e políticas da Meta
