WhatsApp e Automação

Evolution API com problemas: causas, diagnóstico e soluções

Evolution API parou, desconecta ou não gera QR Code? Veja causas comuns envolvendo Docker, banco, Redis, proxy, WhatsApp e integrações com n8n.

Publicado em 31 de julho de 2026Atualizado em 17 de setembro de 2026

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

Se a Evolution API parou, desconecta do WhatsApp ou não gera QR Code, o erro pode estar no serviço ou container, no banco de dados, no Redis quando utilizado, no proxy reverso, na rede, no webhook ou na integração com n8n. Comece pelos logs e pela conexão da instância para identificar a camada afetada antes de alterar a instalação.

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.

O diagnóstico deve 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 receptor indisponível.

Evolution API parou de funcionar: o que verificar primeiro?

1.Verifique se o serviço ou container está ativo e estável.
2.Analise os logs desde a inicialização e no momento da falha.
3.Confirme banco de dados e Redis, quando utilizados.
4.Verifique proxy reverso, DNS e certificado SSL.
5.Confirme a conexão da instância com o WhatsApp.
6.Teste webhooks e integrações externas, incluindo n8n.
7.Compare com alterações recentes de versão ou configuração.

Como verificar se a Evolution API está funcionando?

Observe separadamente o serviço, a instância e a entrega dos eventos. Um container ativo não significa, por si só, que o WhatsApp está conectado ou que o webhook chega ao destino.

Serviço: veja se o processo ou container permanece ativo, se a aplicação responde e se os logs mostram erros ou reinícios.
Dependências: confira acesso ao banco e ao Redis, quando configurado, além de respostas do proxy e da aplicação.
Instância: confira o estado da conexão com o WhatsApp e os eventos registrados ao tentar conectar ou enviar mensagens.
Integrações: confirme se o webhook é disparado, alcança o receptor e recebe resposta adequada, inclusive no n8n.

Evolution API parou de funcionar: causas mais comuns

As dependências variam conforme a versão e a arquitetura da instalação. Localize o primeiro erro nos logs e compare com mudanças recentes antes de reiniciar ou recriar recursos.

Servidor e container

Container parado ou reiniciando, falta de memória, disco ou outros recursos, variáveis incorretas e volumes sem persistência.

Banco e Redis

Banco indisponível, credenciais ou migrations incorretas e Redis indisponível quando utilizado na instalação.

Rede e acesso

Rede entre serviços, proxy reverso Nginx ou Traefik, DNS e certificado SSL podem afetar acesso e comunicação.

Sessão e integrações

Instância desconectada do WhatsApp, atualização incompatível, mudanças de configuração, webhook ou receptor externo com falha.

Onde o problema pode estar?

A falha nem sempre está na própria Evolution API. Cada camada pode impedir o acesso, a conexão com o WhatsApp ou a entrega de eventos, conforme a arquitetura do ambiente.

1.Servidor Linux
2.Docker
3.Evolution API
4.Banco / Redis
5.Nginx ou Traefik
6.WhatsApp
7.Webhook / n8n / sistemas externos

Investigar o servidor Linux e sua rede ajuda a distinguir falhas de infraestrutura das falhas de instância ou integração.

Quando a Evolution API não gera QR Code

Confira se a API está operacional e se a instância iniciou a conexão via WhatsApp Web. Uma sessão existente, falha no container, banco ou Redis quando usado, configuração divergente ou problema de rede pode impedir o pareamento. Antes de apagar a sessão, consulte seu estado e os logs da tentativa de conexão.

Veja a sequência de diagnóstico e os casos específicos no guia Evolution API não gera QR Code.

WhatsApp desconecta repetidamente da Evolution API

Quando a Evolution API fica desconectando, registre o momento 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. Consulte o guia de problemas comuns no n8n se o evento chega ao destino, mas a automação falha.

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 momento 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 faz sentido procurar suporte para Evolution API?

Procure suporte quando a integração em produção falha e não há clareza sobre a camada afetada, especialmente se várias instâncias foram atingidas ou não existe backup confiável.

Serviço parou após uma atualização ou o container entra em loop.
QR Code não funciona ou a instância desconecta repetidamente.
Webhooks pararam ou a integração com n8n falha.
Proxy ou SSL apresenta erro e o ambiente funciona de forma intermitente.
Banco ou Redis apresenta falha e não está claro qual camada causou o problema.

A Jupiter TI atua no diagnóstico do ambiente completo, incluindo Linux, Docker, proxy, banco de dados e integrações e automações. A correção proposta depende da análise dos logs, da versão, da arquitetura e do impacto operacional.

Preciso de ajuda com Evolution API

Fontes técnicas para aprofundar o diagnóstico

Endpoints, variáveis e requisitos podem mudar entre versões; use sempre a documentação e as notas de versão correspondentes à imagem instalada para conferir os detalhes técnicos.

Perguntas frequentes

Por que a Evolution API para de funcionar?

A causa pode estar no container, na falta de recursos, em banco ou Redis quando utilizados, na rede, no proxy, na sessão da instância ou em uma mudança de versão. Compare os logs com as alterações recentes.

Como saber se a Evolution API está funcionando?

Verifique se o serviço permanece ativo, se a aplicação responde, se a instância está conectada e se eventos chegam às integrações. Logs, banco, Redis quando usado e proxy ajudam a localizar falhas parciais.

Por que a Evolution API desconecta do WhatsApp?

Sessão inconsistente, container reiniciando, perda de persistência, falta de recursos, rede instável ou encerramento externo da conexão podem causar desconexões. Os logs e o estado da instância ajudam a distinguir os casos.

Por que o QR Code da Evolution API não aparece?

A instância pode não ter iniciado a conexão, já possuir sessão, ou estar bloqueada por falha no container, banco, Redis quando utilizado, rede ou configuração. Consulte o guia específico de QR Code antes de recriar a instância.

Docker pode causar problemas na Evolution API?

Sim. Reinícios, rede entre containers, volumes, portas e variáveis incorretas podem impedir a inicialização ou a comunicação com outros serviços. Analise a configuração e os logs da instalação.

Banco de dados ou Redis podem derrubar a Evolution API?

Podem, dependendo da versão e da arquitetura. Banco inacessível, migrations pendentes ou Redis indisponível quando configurado podem afetar a inicialização, a sessão ou outras operações.

Problemas no Nginx ou Traefik podem afetar a Evolution API?

Sim. Proxy, DNS ou SSL incorretos podem impedir o acesso externo à API ou a entrega de webhooks mesmo quando o container continua ativo. Verifique as respostas da aplicação e do proxy separadamente.

A Evolution API pode parar após uma atualização?

Pode. Mudanças de versão podem exigir novas variáveis, migrations ou ajustes de integração. Confira a imagem executada, o changelog, os logs de inicialização e o backup antes de alterar o ambiente novamente.

A Jupiter TI oferece suporte para Evolution API?

Sim. A Jupiter TI pode analisar remotamente servidor, Docker, instâncias, logs, banco de dados, Redis, proxy e integrações, conforme o escopo identificado na triagem inicial gratuita.

O suporte pode analisar n8n e Evolution API juntos?

Sim. Quando a falha envolve webhooks ou automações, podemos investigar a Evolution API, a entrega do evento e o recebimento no n8n para localizar a camada afetada.

Continue a investigação