---
title: Principais erros retornados pela API Oficial do WhatsApp (Meta) e como resolver
description: "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…"
url: "https://docs.smclick.com.br/docs/principais-erros-retornados-pela-api-oficial-do-whatsapp-meta-e-como-resolver/"
updated: "2026-02-06"
category: WhatsApp API Oficial
---

# Principais erros retornados pela API Oficial do WhatsApp (Meta) e como resolver

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
