Erros comuns do WhatsApp (Evolution API)

WhatsApp via Evolution API tem comportamento próprio porque depende de uma instance que você controla (self-hosted ou via provider). Erros podem ser nossos, deles ou do WhatsApp.

"Connection state: close"

Causa: a instance Evolution perdeu o link com o WhatsApp Web. Acontece quando:

• Você abriu web.whatsapp.com no navegador (desconecta a Evolution)
• O celular ficou >2 semanas sem internet
• Você desligou da sua conta no WhatsApp via app

Solução:

1. Vai no painel da Evolution
2. Reabre o QR code da instance
3. Escaneia com o celular (Configurações → Dispositivos conectados → Conectar)
4. Quando voltar pra open, no Fala Cheese vai em Conectar WhatsApp e revalida

"Instance not found"

Causa: o nome da instance que você cadastrou no Fala Cheese não existe (ou foi deletada) na Evolution.

Solução:

1. Confirma o nome exato no painel Evolution
2. /app/settings/connections → Editar conexão → corrige campo instanceName

"API key invalid"

Causa: ou a key da Evolution foi rotacionada, ou você copiou errado (espaço extra, char trocado).

Solução: copia novamente do painel Evolution (botão "Copy" pra não dar typo) e cola em /app/settings/connections.

"Number is not registered on WhatsApp"

Causa: o destinatário não tem WhatsApp ativo nesse número.

Solução:

• Confirma o formato: número internacional sem +, ex. 5511999999999
• Confirma que o destinatário tem WhatsApp instalado
• Se sim e ainda dá erro, tenta <numero>@s.whatsapp.net em vez de só o número

Mensagem chega vazia ou cortada

Causa: encoding de caracteres especiais (acentos, emojis) falhando.

Solução: garante que sua instance Evolution está com Content-Type: application/json; charset=utf-8. Se rodando self-hosted, atualiza pra versão >= v2.0 (suporta UTF-8 nativo).

"Rate limit exceeded" (do lado da Evolution)

Causa: estouro de mensagens em pouco tempo. WhatsApp detecta comportamento de bot.

Solução:

• Espalha envios: 1 mensagem a cada 3-5 segundos é seguro
• Reduz volume: menos de 50 mensagens/dia até a conta ganhar "warmup"
• Pausa 24h se hit hard limit antes de tentar de novo

Veja WhatsApp best practices pra estratégia.

"Conta banida pelo WhatsApp"

Causa: você disparou mensagens demais ou pra lista sem opt-in. WhatsApp identifica e bana.

Recuperação:

1. Manda email pra support@whatsapp.com explicando uso legítimo (cliente conhecido, opt-in, etc.)
2. Espera 24-72h pelo retorno (taxa de recuperação ~30%)
3. Plano B: usa outro número (compra chip dedicado pra marketing) e recomeça warmup
4. Aprende: leia WhatsApp best practices antes de voltar

Vídeo grande não envia

Limite prático: WhatsApp Web suporta até 16MB em vídeo via Evolution API.

Solução:

• Comprime vídeo (ffmpeg, HandBrake, ou serviço online) pra menos de 16MB
• Pra vídeo maior, sobe pro YouTube/Vimeo unlisted e manda link

Áudio cortado

Causa: arquivo de áudio com codec não suportado (FLAC, M4A não-AAC).

Solução: converte pra OGG ou MP3 antes. WhatsApp Web aceita esses dois com qualquer bitrate.

Reconectar instance sem perder histórico

A instance Evolution guarda histórico de mensagens enviadas. Se você precisar reescanear o QR (perda de sessão), o histórico permanece na Evolution. Mensagens NÃO duplicam ao reconectar — só retoma de onde parou.

Pra confirmar: o painel Evolution tem timestamp da última msg. Compara antes e depois.

Quando NÃO é problema do Fala Cheese

Antes de abrir ticket conosco, testa:

1. Painel Evolution direto — manda mensagem pelo dashboard deles. Se falhar lá, é problema da instance, não nosso
2. Outra instance — se você tem mais de uma, testa cruzado
3. WhatsApp Web no navegador — se o número também não funciona lá, é problema do WhatsApp, não da Evolution