WhatsApp e Automação

Evolution API não conecta? Veja os principais problemas e soluções

Evolution API não conecta ou não gera QR Code? Veja como diagnosticar falhas em Docker, webhooks, PostgreSQL, Redis e integrações com WhatsApp.

Por Jupiter TIAtualizado em 31 de julho de 202616 min de leitura

O que é a Evolution API e por que ela pode parar de funcionar

A Evolution API expõe recursos do WhatsApp por uma API REST e permite integrar mensagens, eventos e instâncias a ferramentas como n8n, sistemas de atendimento, CRMs e aplicações próprias. A plataforma suporta conexão baseada em WhatsApp Web, por meio do Baileys, e também a API oficial do WhatsApp Business da Meta. O fluxo de QR Code está ligado principalmente à conexão via WhatsApp Web.

Embora o uso diário pareça simples, a operação depende de várias camadas: processo Node.js, container Docker, sessão da instância, PostgreSQL ou outro banco compatível, Redis, proxy reverso, certificado SSL, DNS, rede da VPS e comunicação com serviços externos. Um erro na Evolution API pode nascer em qualquer uma delas.

O diagnóstico deve primeiro separar infraestrutura, configuração e limitação externa. Se o container não inicia, o problema é diferente de uma instância ativa que perdeu a sessão; e uma API saudável não consegue entregar webhooks a um endpoint do n8n que esteja indisponível.

Evolution API não gera QR Code

Quando a Evolution API não gera QR Code, comece verificando se a API está operacional e se a instância realmente entrou no estado de conexão. A ausência do código pode ser um sintoma de falha anterior no banco, no container ou na criação da instância.

Instância criada incorretamente

Confira nome, tipo de integração e se a criação solicitou QR Code. Uma instância configurada para outro provedor não segue necessariamente o fluxo de pareamento via QR.

Sessão antiga ainda registrada

Uma sessão existente, conectada ou incompleta pode impedir um novo fluxo limpo. Consulte o estado da instância antes de desconectar ou remover qualquer dado.

Container com erro

Se a API reinicia, falha durante o bootstrap ou não responde aos endpoints, o QR Code não é a causa principal. Leia os logs desde o início do processo.

Banco indisponível

Falhas de conexão, autenticação ou migrations podem impedir que a instância seja criada ou recuperada corretamente.

Configuração incompleta

Revise SERVER_URL, chave de autenticação, variáveis de banco, Redis e opções da instância conforme a versão instalada.

Versão incompatível

Manager, API, schema do banco ou configuração de uma versão anterior podem divergir. Confirme a imagem realmente executada e as notas de migração.

Problema de rede

DNS, proxy de saída, firewall ou instabilidade podem impedir a conexão externa necessária para iniciar a sessão do WhatsApp.

Limite de tentativas do QR

O projeto possui configuração de limite para geração. Códigos também expiram; mantenha apenas um fluxo de conexão ativo e use o código mais recente.

Sequência segura para investigar o QR Code

1Confirme se a API responde e se o container permanece estável.
2Consulte o estado atual da instância e verifique se ela já está conectada, conectando ou fechada.
3Revise o log da criação ou conexão da instância, procurando o primeiro erro.
4Valide banco, Redis, migrations e variáveis da versão executada.
5Solicite a conexão novamente sem criar instâncias duplicadas ou apagar a sessão antes de entender seu estado.

WhatsApp desconecta repetidamente da Evolution API

Quando a Evolution API fica desconectando, registre o horário e o motivo informado no evento de conexão. Uma reinicialização da API, um logout solicitado pelo WhatsApp e uma falha de rede podem produzir o mesmo sintoma para o usuário, mas exigem correções diferentes.

Causa possível	Sinais comuns	O que verificar
Sessão corrompida	Reconexões em sequência, erro ao restaurar credenciais ou estado inconsistente.	Logs da instância, persistência e histórico da última parada.
Container reiniciando	Uptime curto, contagem de reinícios crescente e todas as instâncias afetadas.	Memória, exit code, healthcheck, banco e logs do processo.
Perda de persistência	A instância pede novo pareamento após deploy ou recriação.	Volumes, caminho montado, banco e configuração de armazenamento da sessão.
Sessão usada em duplicidade	Conflitos logo após subir uma segunda réplica ou instalação.	Replicas, nomes, bancos, prefixos Redis e ambientes que compartilham credenciais.
Limitação externa	Logout, bloqueio, dispositivo removido ou restrição da conta.	Status no WhatsApp, dispositivos vinculados e políticas aplicáveis.
VPS sem recursos	Lentidão, OOM, Redis ou banco instável e timeouts generalizados.	CPU, RAM, swap, disco, I/O e limites dos containers.
Conexão instável	Desconexões coincidem com perda de rede, DNS ou proxy.	Conectividade de saída, resolução DNS, latência e eventos do provedor.

Não trate desconexão externa como falha puramente de servidor. No fluxo baseado em WhatsApp Web, a sessão depende do comportamento do serviço e do dispositivo vinculado. Para operações empresariais que exigem maior previsibilidade e uso em escala, avalie também a API oficial do WhatsApp Business e suas regras.

Evolution API webhook não funciona ou não recebe mensagens

O webhook entrega eventos da Evolution API para outro sistema. Se a instância está conectada, mas o fluxo não recebe mensagens, teste separadamente a geração do evento e a entrega HTTP. O problema pode estar tanto na Evolution quanto no receptor.

URL, DNS e HTTPS

Confirme a URL exata, sem espaços ou caminho antigo, e teste se ela é alcançável a partir do container da Evolution API. localhost aponta para o próprio container, não para outro serviço da VPS. Em uma rede Docker compartilhada, use o hostname interno correto; pela internet, valide DNS e certificado HTTPS.

Eventos e modo por evento

Habilite os eventos necessários, como atualização de conexão, QR Code ou novas mensagens. Quando o modo de webhook por evento está ativo, a Evolution acrescenta um caminho específico à URL base. O receptor precisa expor exatamente essas rotas.

Firewall, proxy reverso e autenticação

Verifique se o firewall e o proxy aceitam requisições da origem, o método HTTP e o tamanho do payload. Se o receptor exige token ou cabeçalho, confirme o que foi cadastrado no webhook. Redirecionamentos, autenticação interativa e WAF podem impedir a entrega.

Webhook de teste e produção no n8n

No n8n, a URL de teste é temporária e depende do editor aguardando o evento. Para uma integração permanente, use a URL de produção e ative o workflow. Também confirme se o domínio público do n8n está correto atrás do proxy reverso.

Resposta do sistema receptor

O endpoint deve responder dentro do tempo esperado com um código HTTP adequado. Respostas 4xx, 5xx, timeout ou fechamento da conexão podem gerar novas tentativas conforme a versão e a configuração. Registre o identificador do evento para evitar processamento duplicado quando houver retry.

Problemas com PostgreSQL, Redis ou outro banco

Na Evolution API v2, o banco armazena informações críticas e é acessado por meio do Prisma. A documentação atual contempla PostgreSQL e MySQL. O Redis atua como cache e pode armazenar informações de conexão conforme as variáveis definidas. Tratar os dois como serviços descartáveis pode causar indisponibilidade ou perda de estado.

Falha	Impacto	Diagnóstico
Credenciais incorretas	API não inicia ou não recupera instâncias.	Usuário, senha, nome do banco, provider e URI completa.
Banco inacessível	Timeout, falha no bootstrap e erros em operações.	Estado do serviço, porta, rede, firewall e limite de conexões.
DNS interno incorreto	Hostname não resolve dentro do container.	Nome do serviço Docker, aliases e rede compartilhada.
Containers em redes diferentes	API, PostgreSQL ou Redis existem, mas não se comunicam.	Networks do Compose ou Coolify e anexação de cada serviço.
Migrations pendentes	Tabelas ou colunas esperadas não existem após atualização.	Notas da versão, etapa de deploy do banco e logs do Prisma.
Variáveis divergentes	A API conecta ao banco, schema ou índice Redis errado.	Ambiente efetivamente carregado pelo container, sem expor segredos.
Sem persistência	Dados desaparecem ao recriar PostgreSQL ou Redis.	Volumes, caminho de dados, política de backup e teste de restauração.

Dentro de containers distintos, não use localhost para apontar ao PostgreSQL ou Redis. O hostname deve representar o serviço alcançável na mesma rede. Em Coolify, confirme a rede e os nomes internos gerados para cada recurso antes de alterar a URI.

Evolution API reiniciando no Docker ou Coolify

Se a Evolution API no Docker entra em loop de reinício, a política restart está apenas tentando recuperar um processo que encerrou. Verifique a contagem de reinícios e leia o início dos logs com docker ps -a e docker logs evolution_api, ajustando o nome ao ambiente.

Variáveis obrigatórias ausentes ou com nomes incompatíveis com a imagem executada.
Porta ocupada no host ou rota do Coolify apontando para uma porta interna diferente da aplicação.
Falta de memória, encerramento por OOM ou VPS saturada durante sincronização e processamento.
Erro de conexão ou migration do banco durante a inicialização.
Imagem incompatível com a arquitetura do servidor ou tag de versão diferente da esperada.
PostgreSQL, Redis, DNS ou outro serviço necessário indisponível no momento do start.
Healthcheck usando caminho, porta ou tempo de inicialização inadequados.
Volume sem permissão, filesystem somente leitura ou disco cheio.

No Coolify, compare os logs do build com os logs da aplicação em execução. Um deploy concluído apenas confirma que a imagem foi criada; não garante que a API conseguiu acessar banco e Redis, executar migrations, permanecer saudável e receber tráfego pelo proxy.

Mensagens não são enviadas pela Evolution API

Antes de reenviar várias vezes, consulte o estado da instância e registre a resposta completa da API. Uma requisição aceita pelo seu sistema não significa necessariamente que o WhatsApp recebeu ou entregou a mensagem.

Número em formato incorreto

Use o formato esperado pelo endpoint, com código do país e DDD, sem máscara, e confirme se o destinatário é válido no WhatsApp.

Instância desconectada

Consulte o estado antes de enviar. Uma instância fechada ou reconectando não processa a mensagem normalmente.

Autenticação incorreta

Revise a apikey global ou da instância, o cabeçalho e o ambiente ao qual a credencial pertence.

Endpoint ou instância errados

Confirme caminho, método HTTP, nome da instância e versão da documentação correspondente à imagem em execução.

Limite ou bloqueio externo

Restrições do WhatsApp, reputação, políticas e comportamento da conta não são corrigidos apenas com reinício da API.

Payload inválido

Valide JSON, campos obrigatórios e estrutura específica para texto, áudio, imagem ou documento.

Mídia inacessível

A URL precisa estar disponível para quem realiza o download, com HTTPS válido, tipo e tamanho compatíveis.

Fila ou dependência travada

Investigue Redis, workers, eventos pendentes, timeouts e consumo de recursos antes de duplicar a solicitação.

Automação não deve ser usada para spam ou mensagens sem consentimento. Respeite as políticas aplicáveis do WhatsApp, a finalidade informada ao contato e a legislação de proteção de dados. Volume, frequência e conteúdo inadequados podem gerar bloqueios que estão fora do controle da infraestrutura.

Cuidados ao atualizar a Evolution API

Atualizar a imagem sem revisar changelog, migrations, variáveis e compatibilidade pode interromper instâncias e integrações em produção. Endpoints, payloads, requisitos de banco, mecanismos de sessão e até condições de ativação podem mudar entre versões.

Em produção, prefira uma tag de versão fixa em vez de latest. Faça backup do banco e dos dados persistentes, registre a configuração atual, valide a nova versão em homologação e teste conexão, QR Code, envio de mensagem, recebimento de webhook e integração com n8n antes de promover a atualização.

Também mantenha um plano de rollback compatível com o schema do banco. Voltar apenas a imagem depois de executar uma migration incompatível pode não restaurar o ambiente anterior.

Checklist de diagnóstico da Evolution API

Reúna estas evidências antes de alterar o ambiente ou solicitar suporte Evolution API:

1Consulte o estado da instância e registre se está aberta, conectando ou fechada.
2Salve os logs da API desde a inicialização e no horário exato da falha.
3Verifique containers, uptime, contagem de reinícios, healthcheck e exit code.
4Confirme versão e arquitetura da imagem realmente executada.
5Teste conectividade, credenciais, schema e migrations do banco.
6Valide URI, prefixo, índice, persistência e disponibilidade do Redis.
7Localize o webhook configurado, os eventos habilitados e o histórico de respostas HTTP.
8Confirme HTTPS, certificado, DNS e proxy reverso da API e do receptor.
9No n8n, use a URL de produção e mantenha o workflow ativo.
10Revise volumes, permissões e persistência da sessão, banco e Redis.
11Meça CPU, RAM, swap, disco, inodes e I/O da VPS.
12Compare variáveis e configuração com a última versão funcional, sem publicar credenciais.
13Registre mudanças recentes: update, deploy, proxy, firewall, banco ou WhatsApp vinculado.
14Confirme se existe backup externo e restauração testada antes de remover qualquer recurso.

Segurança e estabilidade da integração

Uma Evolution API funcional ainda pode estar insegura. Como ela controla mensagens e integrações, trate a API, o manager, o n8n e os bancos como componentes sensíveis da infraestrutura.

Proteja a API

Mantenha autenticação ativa, use chaves longas e exclusivas e limite origens e rotas expostas quando possível.

Não exponha bancos

PostgreSQL e Redis não precisam ficar públicos. Restrinja-os à rede interna e aos serviços autorizados.

Use HTTPS

Termine TLS em um proxy reverso bem configurado e monitore validade do certificado, DNS e redirecionamentos.

Proteja credenciais

Não coloque apikey, senha de banco ou token em código, prints, logs públicos ou repositórios. Use secrets e controle de acesso.

Faça backup

Mantenha cópias fora da VPS, com retenção definida e restauração testada do banco e dos dados persistentes.

Monitore o ambiente

Acompanhe disponibilidade, conexão das instâncias, reinícios, erros de webhook, filas, disco, memória e expiração de certificados.

Separe ambientes

Desenvolvimento e produção devem usar instâncias, bancos, prefixos Redis, credenciais e webhooks independentes.

Atualize com controle

Aplique correções de segurança após testes, com versão fixa, backup, changelog, migrations e rollback planejado.

Quando contratar suporte ou consultoria Evolution API

Procure consultoria Evolution API quando a integração está em produção, várias instâncias foram afetadas, não existe backup confiável, o banco apresenta erros, atualizações falham ou a equipe não consegue separar um problema de WhatsApp de uma falha de Docker, rede ou aplicação.

A Jupiter TI oferece instalação da Evolution API, correção de instâncias, análise de logs, configuração de Docker e Coolify, integração com n8n e automações, configuração de webhooks, análise de PostgreSQL e Redis, migração, backup, monitoramento e suporte remoto para empresas em todo o Brasil.

Também atuamos com servidores Linux, APIs e servidores web, automação com WhatsApp e diagnóstico de infraestrutura. A correção proposta depende da análise dos logs, da versão, da arquitetura e do impacto operacional.

Fontes técnicas para aprofundar o diagnóstico

Este artigo foi revisado em 31 de julho de 2026 com base na documentação e no repositório oficiais. Endpoints, variáveis e requisitos podem mudar entre versões; use sempre a documentação correspondente à imagem instalada.

Perguntas frequentes

Por que a Evolution API não gera QR Code?

Verifique se a instância foi criada com a integração e a opção de QR Code corretas, se já existe uma sessão vinculada e se a API consegue acessar banco, Redis e internet. Falhas de container, migrations pendentes e incompatibilidade de versão também podem interromper a geração.

Por que a Evolution API fica desconectando do WhatsApp?

As causas podem incluir perda ou corrupção da sessão, container reiniciando, armazenamento não persistente, uso simultâneo da mesma sessão, falta de recursos, instabilidade de rede ou encerramento externo da conexão pelo WhatsApp. Logs e estado da instância ajudam a separar essas hipóteses.

Por que o webhook da Evolution API não chega ao n8n?

Confirme a URL cadastrada, os eventos habilitados, a validade do HTTPS e se o endpoint está acessível a partir do container da Evolution API. No n8n, diferencie a URL temporária de teste da URL de produção e mantenha o workflow de produção ativo.

A Evolution API precisa de PostgreSQL e Redis?

Na Evolution API v2, o banco armazena informações críticas e o Redis é usado como cache e pode participar do armazenamento de estado conforme as variáveis configuradas. A necessidade e o papel exato dependem da versão e da arquitetura escolhida.

É seguro atualizar a Evolution API usando a tag latest?

Em produção, é mais previsível fixar uma versão testada. Antes de atualizar, leia o changelog e o guia de migração, faça backup, revise variáveis e migrations e valide a nova imagem em homologação com as integrações existentes.

A Jupiter TI oferece suporte para Evolution API e n8n?

Sim. A Jupiter TI oferece instalação, diagnóstico e suporte remoto para Evolution API, Docker, Coolify, n8n, webhooks, PostgreSQL, Redis, migração, backup e monitoramento para empresas em todo o Brasil.

Jupiter TI

Precisa de suporte Evolution API para restaurar sua integração?

Sua Evolution API não conecta, não gera QR Code ou parou de enviar mensagens? A Jupiter TI pode analisar sua instalação, identificar a causa e restaurar o funcionamento da integração com segurança, conforme o diagnóstico do ambiente.

Solicitar suporte Falar com a Jupiter TI Analisar minha Evolution API