O que significa o erro 515 (restartRequired) no Baileys logo após ler o QR Code?

No protocolo Multi-Device do WhatsApp Web, após o pareamento criptográfico inicial (creds.update), o servidor fecha o WebSocket com código 515 exigindo que o cliente reconecte usando as chaves salvas. Se o seu código tratar 515 como falha fatal ou apagar a pasta auth_info, o pareamento falha sempre.

Como diferenciar queda de rede do erro 401 (DisconnectReason.loggedOut)?

Verifique (lastDisconnect?.error)?.output?.statusCode !== DisconnectReason.loggedOut. Apenas quando o código é 401 (loggedOut) a pasta auth_info deve ser limpa para gerar um novo QR Code. Em qualquer outro código (515, 408, 428), mantenha as credenciais e reconecte com backoff.

Como resolver a mudança de URL do túnel gratuito trycloudflare.com em webhooks?

Usando um orquestrador em Python que lê o stdout do cloudflared, captura a nova URL HTTPS via regex e faz uma chamada PATCH automática na API do Cloudflare Pages para atualizar a variável EVOLUTION_API_URL em produção.

Início › Engenharia & GitHub Debug › Baileys v7 Erro 401/515 & Auto-Tunnel

github debug & fix Baileys v7 Cloudflare Tunnel Node.js + Python

Publicado em 17/10/2026 · Medido em produção na porta 8080 (Build WhatsApp Web 2.3000.1043857760)

Baileys v7 Erro 401 e 515: Por Que o Código do GitHub Cai e Como Criamos um Gateway WhatsApp Auto-Sincronizado

Todo dia dezenas de desenvolvedores clonam repositórios de WhatsApp no GitHub para escapar de mensalidades de R$ 150 a R$ 290 de APIs terceirizadas — e batem de frente com três muros técnicos: o fechamento imediato com statusCode: 515 após ler o QR Code, o loop infinito no erro 401 loggedOut e a troca de URL do túnel gratuito da Cloudflare. Veja como resolvemos os três na nossa própria máquina.

📋 Neste Dossiê Técnico:

Por que 90% dos exemplos de Baileys no GitHub falham em 2026
Anatomia dos códigos 515 (Restart Required), 401 (Logged Out) e 405 (Version Mismatch)
🛠️ Ferramenta Interativa: Diagnosticador de Erros Baileys + Calculadora Self-Hosted
O Segredo: Como sincronizar a URL dinâmica do trycloudflare.com direto na API do Cloudflare Pages
📦 Deploy Kit Completo (Demonix WhatsApp Gateway v7) + Repositório Aberto no GitHub

1. O Problema Real: O que acontece quando você roda os exemplos do GitHub

Quando publicamos nosso primeiro repositório de integração serverless (Stripe no WhatsApp em 184ms), ele recebeu 149 clones de 75 desenvolvedores únicos em menos de duas semanas. Mas a pergunta técnica que mais se repetia era sempre a mesma: "Como vocês mantêm o motor do WhatsApp conectado na máquina local sem pagar mensalidade de Z-API ou VPS dedicada?"

Se você copiar o código padrão da maioria dos tutoriais de @whiskeysockets/baileys no GitHub, este é o trecho que derruba a sua aplicação:

// ❌ CÓDIGO DE EXEMPLO COMUM NO GITHUB (QUE FALHA EM PRODUÇÃO) const sock = makeWASocket({ auth: state, printQRInTerminal: true // Depreciado e trava em servidores headless }); sock.ev.on('connection.update', (update) => { if (update.connection === 'close') { // ERRO 1: Reconecta cegamente mesmo em 401 (gera loop infinito sem novo QR) // ERRO 2: Ou apaga a pasta auth_info no código 515 logo após o pareamento! startSock(); } });

Telemetria da nossa máquina local (17/10/2026):
• Build WhatsApp Web exigida no handshake: 2.3000.1043857760
• Tempo de subida do túnel HTTPS (cloudflared): 5,0 segundos
• Tempo de atualização da variável EVOLUTION_API_URL no Cloudflare Pages via API: 4,1 segundos

2. A Correção no `server.js`: Tratamento Determinístico de 401, 515 e Versão

Para que o gateway opere 24/7 sem intervenção manual, o gerenciador de estado do WebSocket precisa separar três eventos completamente distintos no protocolo Multi-Device:

1º Handshake de Versão (Evita Erro 405): Antes de abrir o socket, é obrigatório consultar await fetchLatestBaileysVersion(). Sem isso, qualquer atualização silenciosa da Meta invalida a versão hardcoded da biblioteca.
2º Código 515 (restartRequired): Quando você lê o QR Code no celular, o WhatsApp grava as chaves criptográficas em creds.update e força o fechamento da conexão com código 515 para que o cliente reabra o socket autenticado. Nosso código preserva a pasta auth_info/ e agenda setTimeout(startWhatsApp, 3000).
3º Código 401 (DisconnectReason.loggedOut): Só ocorre quando o aparelho é desconectado manualmente no celular ou a sessão expira. Nesse caso específico, manter auth_info/ trava o servidor. Nosso código executa fs.rmSync(AUTH_DIR, { recursive: true, force: true }), recria a pasta e gera automaticamente um novo QR Code em Base64 no painel web (http://localhost:8080).

// ✅ NOSSA IMPLEMENTAÇÃO VALIDADA EM PRODUÇÃO (server.js) const { version } = await fetchLatestBaileysVersion(); log(`Versao Baileys: ${version.join('.')}`); // Ex: 2.3000.1043857760 sock.ev.on('connection.update', async (update) => { const { connection, lastDisconnect, qr } = update; if (qr) { connectionStatus = 'AGUARDANDO_QR'; latestQRImage = await QRCode.toDataURL(qr, { width: 320, margin: 2 }); } if (connection === 'close') { const statusCode = (lastDisconnect?.error)?.output?.statusCode; const shouldReconnect = statusCode !== DisconnectReason.loggedOut; connectionStatus = 'DESCONECTADO'; if (shouldReconnect) { // Código 515, 408 ou oscilação de rede: preserva auth_info e reconecta em 3s setTimeout(startWhatsApp, 3000); } else { // Código 401 (loggedOut): limpa credenciais corrompidas e gera novo QR Code fs.rmSync(AUTH_DIR, { recursive: true, force: true }); fs.mkdirSync(AUTH_DIR, { recursive: true }); setTimeout(startWhatsApp, 3000); } } });

⚡ Quer o Gateway v7 + Painel QR Web + Orquestrador Auto-Tunnel prontos?

Baixe o Deploy Kit completo testado em produção por R$ 37,00 (pagamento único, sem mensalidade).

Baixar Deploy Kit (R$ 37) →

3. 🛠️ Ferramenta Interativa: Diagnosticador Baileys & Simulador de Economia

Selecione abaixo o código de erro que está aparecendo no seu terminal ou simule a economia anual de substituir uma API comercial paga pelo seu próprio gateway local com rota compatível com a Evolution API (/message/sendText/:instance):

🔬 Diagnosticador de Status Code Baileys + Calculadora Self-Hosted

Código de Desconexão no Log (`statusCode`):

Mensalidade atual de API de WhatsApp (R$/mês): R$ 150

Diagnóstico de Engenharia & Ação Automática do Gateway:

R$ 0/mês

Custo Gateway Local + Cloudflare

R$ 1.800

Economia Anual Estimada (12 meses)

4. O Pulo do Gato: Sincronizando o Túnel Dinâmico (`trycloudflare.com`) com a Borda

Mesmo depois de estabilizar o Baileys na porta 8080, resta um problema clássico: como fazer um Worker na nuvem (como o nosso webhook da Stripe no Cloudflare Pages) conversar com o seu computador local se o túnel gratuito cloudflared tunnel --url http://localhost:8080 gera um subdomínio diferente toda vez que reinicia?

Nossa solução foi criar o orchestrator.py. Em vez de atualizar variáveis de ambiente na mão, o script monitora a saída padrão (stdout) do processo cloudflared e, no exato segundo em que o link https://xxxx.trycloudflare.com aparece, dispara um PATCH autenticado na API do Cloudflare Pages:

[08:33:04] [ORQUESTRADOR] Iniciando Baileys Gateway Node.js (server.js)... [08:33:06] [ORQUESTRADOR] 🟢 WHATSAPP CONECTADO COM SUCESSO! Número: 554799835120 [08:33:06] [ORQUESTRADOR] Iniciando Cloudflare Tunnel na porta 8080... [08:33:11] [ORQUESTRADOR] 🌐 TÚNEL ATIVO: https://assessed-cir-vienna-anniversary.trycloudflare.com [08:33:15] [ORQUESTRADOR] ✅ Cloudflare Pages atualizado com sucesso! EVOLUTION_API_URL sincronizada.

Nota de transparência e arquitetura: O Baileys é uma implementação não-oficial do protocolo WhatsApp Web voltada para automações internas, alertas transacionais (como notificações de vendas para o próprio lojista) e ambientes de laboratório. Para operações de atendimento massivo com SLA corporativo, avalie um túnel nomeado em domínio próprio ou a API Cloud Oficial da Meta.

5. Código Aberto de Referência vs. Deploy Kit Completo (R$ 37,00)

Seguindo a diretriz de transparência do nosso laboratório, todos os blocos essenciais de reconexão seletiva (Erros 401/515/405) e o pareamento via QR Code estão documentados integralmente nos passos acima para quem deseja montar sua própria estrutura do zero.

Se você quiser economizar horas de configuração e receber o pacote completo pronto para produção (incluindo o painel Dark-Mode com QR Code Base64 ao vivo, o orchestrator.py com sincronização automática da API da Cloudflare e o guia completo de troubleshooting), adquira o Deploy Kit Oficial abaixo:

⚡ Demonix WhatsApp Gateway v7 — Deploy Kit Completo

Receba imediatamente o arquivo demonix_whatsapp_gateway_v7_kit.zip com o server.js completo (Painel QR Web + Anti-Queda 401/515 + Rotas Evolution API) + orchestrator.py (Auto-Sync Cloudflare Pages) + Guia de Implantação Rápida.

Comprar Deploy Kit WhatsApp Gateway v7 (R$ 37,00) 🔒 Pix & Cartão

Pagamento único de R$ 37,00 processado via Stripe por Real Make IA · Download imediato pós-pagamento