Existe um padrão nos grupos de suporte de Evolution API: as mesmas cinco perguntas, todos os dias, feitas por pessoas diferentes. Não porque a comunidade não responda (responde, e bem), mas porque os sintomas se repetem por natureza da arquitetura. Este artigo é o mapa desses sintomas: o que cada um significa, o diagnóstico em ordem de probabilidade e o ponto em que o problema deixa de ser técnico.
TL;DR: Os cinco problemas mais recorrentes da Evolution API: QR code que não gera, instância que desconecta sozinha, webhook que para de entregar eventos, mensagem enviada sem erro que não chega e consumo de memória crescente na VPS. Quatro dos cinco têm diagnóstico técnico resolvível; o quinto elemento comum a todos é estrutural: a conexão via protocolo web, que o próprio repositório do projeto (2026) admite ter limitações frente às APIs oficiais.
1. QR code não gera ou não conecta
O campeão de frequência (a busca por essa dúvida específica supera a maioria das buscas sobre a ferramenta). Ordem de diagnóstico: versão da Evolution API desatualizada frente ao protocolo (causa mais comum após updates do WhatsApp), instância em estado zumbi que precisa ser deletada e recriada, e recursos insuficientes na VPS na hora de gerar a sessão. O passo a passo completo, incluindo o caso do QR que conecta e cai em segundos, está em Evolution API não gera QR code.
2. Instância desconecta sozinha
A desconexão intermitente tem três suspeitos em ordem: o servidor da Meta derrubando sessões web (acontece em ondas, tipicamente após atualização de protocolo), memória insuficiente derrubando o processo e o celular âncora fora do ar por tempo demais. O diagnóstico diferencial e as correções estão em Evolution API desconectando toda hora. O dado incômodo: a primeira causa, a mais comum em ondas coletivas, não tem correção do seu lado. Só espera.
3. Webhook mudo (eventos que não chegam)
Fluxo do diagnóstico: confirme que a instância está conectada (sem sessão, não há evento); teste a URL do webhook por fora (curl direto; certificado SSL vencido é clássico silencioso); verifique se os eventos esperados estão assinados na configuração da instância; e, se tudo acima passa, procure mudança de payload após atualização, porque campo renomeado quebra consumidor sem gerar erro em lugar nenhum. Quem integra via n8n encontra os padrões de proteção em Evolution API + n8n.
4. Mensagem “enviada” que não chega
O mais traiçoeiro, porque não há erro para olhar. Causas em ordem: sessão degradada (conectada no painel, morta no protocolo; reiniciar a instância resolve o episódio), número destinatário que bloqueou ou denunciou, e destinatário com sinais de conta inexistente. Quando o padrão é coletivo (várias conversas, mesmo horário), o suspeito é degradação de sessão ou início de restrição sobre o número, e aí vale ler os sinais de bloqueio de número na Evolution API antes que o silêncio vire ban.
5. Memória crescendo até travar
Sessões acumulam cache, logs crescem, mídia baixada fica. Em VPS justa, o ciclo termina em OOM e derruba tudo que mora na máquina (inclusive o n8n e o Chatwoot, se estiverem juntas). Mitigações: limite de log com rotação, limpeza programada de mídia, Redis para descarregar o processo e, na raiz, dimensionamento honesto da máquina, o tema de VPS para Evolution API.
O sexto problema, que engloba os cinco
Repare no que os cinco têm em comum: nenhum é um bug exótico. São modos de falha de uma arquitetura que simula um cliente web sobre um protocolo que muda sem aviso. A manutenção não é um período de ajuste inicial; é o estado permanente da operação. A partir de certa escala, o troubleshooting recorrente vira o argumento decisivo para trocar de regime: sobre a API oficial, webhook é documentado, sessão não existe (a conexão é da plataforma) e o modo coexistência mantém o celular ativo, como detalha o nosso guia de migração com coexistência. Operar isso pronto, com caixa de entrada e automação juntas, é o que o Cubo Suite entrega; interesse declarado, como sempre por aqui.
Como saber se o problema é da minha instância ou geral?
Cheque os canais da comunidade (grupos, issues do repositório) antes de mexer em produção: quedas por atualização de protocolo acontecem em ondas e enchem os canais em minutos. Se a onda é coletiva, a correção é atualizar quando sair release, não reconfigurar a sua VPS.
Reiniciar a instância resolve a maioria dos casos?
Resolve o episódio de sessão degradada, que é frequente, e não resolve a causa. Reinício virando rotina é sintoma de memória insuficiente, versão defasada ou onda de protocolo, e merece diagnóstico em vez de cron de restart, que só esconde o problema.
Atualizar a Evolution API sempre corrige?
Corrige quando o problema é defasagem frente ao protocolo, e introduz risco próprio: payloads e comportamentos mudam entre versões. Atualize em janela controlada, com backup e teste do caminho crítico, nunca em sexta-feira à tarde.
Deixe um comentário