Corrigir Tempestade de Reconexão WebSocket do Bot do Discord em Oscilações de Rede

Quando seu bot do Discord perde a conexão durante uma breve oscilação de rede, ele pode tentar se reconectar centenas de vezes por minuto. Esse ciclo rápido de reconexão, conhecido como tempestade de reconexão WebSocket, pode causar limites de taxa, banimentos de IP e degradação do serviço do seu bot. A tempestade acontece porque a lógica de reconexão padrão do bot não espera o suficiente entre as tentativas. Este artigo explica por que as tempestades de reconexão ocorrem e fornece correções concretas no nível do código para detê-las.

Por que as Tempestades de Reconexão WebSocket Acontecem

Um bot do Discord mantém uma conexão WebSocket persistente para receber eventos. Quando a rede cai por uma fração de segundo, a biblioteca WebSocket do bot detecta a desconexão e imediatamente dispara um evento de reconexão. Sem um atraso, o bot envia uma nova solicitação de conexão instantaneamente. Se a rede ainda estiver instável, a nova conexão falha e o ciclo se repete.

A API Gateway do Discord espera que os clientes usem backoff exponencial — esperar 1 segundo, depois 2, depois 4, e assim por diante — antes de tentar reconectar. Muitas bibliotecas de bot usam reconexão imediata por padrão. Isso viola os limites de taxa do Discord e pode resultar no bloqueio temporário do seu bot no Gateway.

O Papel do Gateway do Discord

O Gateway é o endpoint WebSocket que entrega eventos em tempo real como mensagens, atualizações de membros e mudanças de estado de voz. Cada sessão do bot deve manter uma conexão Gateway. Quando ocorre uma tempestade de reconexão, o bot abre e fecha várias conexões Gateway em segundos. A limitação do lado do servidor do Discord entra em ação, retornando HTTP 429 (Muitas Requisições) ou até fechando a conexão com um erro 4004 (Falha de Autenticação).

Passos para Corrigir a Tempestade de Reconexão WebSocket

Estes passos se aplicam ao Discord.js v14 e bibliotecas similares. Ajuste os nomes das variáveis se estiver usando discord.py ou outros wrappers.

1. Habilitar Backoff Exponencial nas Opções do Client
   No Discord.js, defina reconnectDelay e maxReconnectAttempts ao criar o client. Exemplo: const client = new Client({ intents: [GatewayIntentBits.Guilds], reconnectDelay: 1000, maxReconnectAttempts: 10 }); Isso instrui a biblioteca a esperar 1 segundo antes da primeira tentativa e dobrar o atraso a cada vez.
2. Adicionar Jitter para Evitar Efeito Manada
   Jitter adiciona milissegundos aleatórios ao atraso para que várias instâncias do bot não reconectem simultaneamente. No Discord.js, você pode implementar jitter no evento reconnecting: client.on('reconnecting', () => { const jitter = Math.random() * 2000; setTimeout(() => client.login(token), 1000 + jitter); }); Isso distribui as tentativas de reconexão.
3. Implementar uma Proteção de Estado da Conexão
   Rastreie o timestamp da última reconexão em uma variável. Se um evento de reconexão ocorrer dentro de 5 segundos da última tentativa, ignore-o. Exemplo: let lastReconnect = 0; client.on('reconnecting', () => { const now = Date.now(); if (now - lastReconnect < 5000) return; lastReconnect = now; // prosseguir com a reconexão });
4. Usar o Módulo de Reconexão Oficial do Discord.js
   O pacote @discordjs/ws fornece backoff exponencial embutido. Substitua o código WebSocket bruto por WebSocketManager desse pacote. Instale com npm install @discordjs/ws e configure reconnectAttempts e reconnectDelay no WebSocketManagerOptions.
5. Monitorar a Latência do Gateway e os Códigos de Desconexão
   Registre o código de fechamento WebSocket em cada desconexão. Códigos 1000 (fechamento normal) e 1001 (indo embora) são seguros de ignorar. O código 4009 indica tempo limite da sessão — aumente seu atraso de reconexão para pelo menos 10 segundos. O código 4004 significa token inválido — pare de reconectar imediatamente e alerte o administrador.

Se o Bot Ainda Reconectar de Forma Agressiva

Bot Reconecta Mesmo Após Implementar Backoff

Algumas bibliotecas de bot, especialmente versões antigas do discord.py, não respeitam atrasos de reconexão personalizados. Atualize para a versão mais recente da biblioteca. Para discord.py 2.3+, defina reconnect=True e a biblioteca lida com o backoff automaticamente. Se estiver usando uma biblioteca WebSocket personalizada, certifique-se de não estar chamando connect() dentro do evento on_disconnect — isso cria um loop.

Limite de Taxa (HTTP 429) Ainda Aparece

Se seu bot receber erros 429 após corrigir a tempestade de reconexão, o limite de taxa pode ser de outra parte do seu código, como envio de mensagens ou chamadas à API REST. Verifique o cabeçalho Retry-After na resposta 429. Implemente um limitador de taxa global usando o tratamento de bucket embutido do @discordjs/rest. Não ignore respostas 429 — elas podem escalar para um banimento permanente.

Bot Fica Offline Após a Rede se Recuperar

Se o bot parar de reconectar completamente após uma oscilação de rede, sua proteção de reconexão pode estar muito restritiva. Reduza o intervalo mínimo de 5 segundos para 2 segundos e certifique-se de que a proteção seja redefinida após uma conexão bem-sucedida. Adicione client.on('ready', () => { lastReconnect = 0; }) para limpar a proteção no login bem-sucedido.

Prevenção de Tempestade de Reconexão: Nível de Código vs Nível de Biblioteca

Item	Proteção em Nível de Código	Opção em Nível de Biblioteca
Esforço de implementação	Escrever lógica personalizada em eventos	Definir valores de configuração no construtor
Flexibilidade	Controle total sobre atraso e jitter	Limitado aos padrões da biblioteca
Risco de bloqueio	Possível se a lógica de proteção estiver errada	Baixo — a biblioteca lida com casos extremos
Melhor para	Implementações WebSocket personalizadas	Usuários de Discord.js, discord.py, JDA

Use opções de nível de biblioteca primeiro. Elas são testadas por milhares de bots. Adicione uma proteção de nível de código apenas se a biblioteca não suportar backoff ou se você precisar de valores de jitter personalizados.

Após aplicar as correções acima, seu bot sobreviverá a oscilações de rede sem desencadear tempestades de reconexão. Teste o comportamento desconectando sua internet por 10 segundos enquanto o bot está em execução. Observe os logs — você deve ver uma única tentativa de reconexão após um atraso, não uma enxurrada. Para bots de produção, ative também o registro de intenções do Gateway para rastrear retomadas de sessão. Um bot saudável retoma sua sessão sem reidentificar, o que economiza largura de banda e evita limites de taxa.