Corrigir Limite de Taxa do Webhook do Discord em Notificações em Rajada dos Logs

Você vê a mensagem de erro “You are being rate limited” nos logs do servidor após enviar várias notificações de um bot ou integração. Isso acontece quando seu webhook envia mais de 5 requisições por segundo para a API do Discord. O Discord impõe esse limite para evitar spam e proteger o desempenho do servidor. Este artigo explica por que notificações em rajada disparam o limite de taxa e fornece correções passo a passo para reduzir a frequência de requisições e adicionar lógica de retry.

Por que o Webhook do Discord Limita Notificações em Rajada

A API de webhook do Discord impõe um limite de taxa de 5 requisições por segundo por URL de webhook. Esse limite é medido em uma janela contínua de 1 segundo. Quando seu bot de logs ou integração envia várias notificações em rápida sucessão, ele ultrapassa esse limite. A API retorna um código de status HTTP 429 com um corpo JSON contendo a mensagem de erro “You are being rate limited” e um campo retry_after em milissegundos.

A rajada ocorre com mais frequência quando um único evento dispara várias entradas de log. Por exemplo, uma ação de moderação no servidor que expulsa 10 usuários de uma vez pode tentar enviar 10 mensagens de webhook separadas em uma fração de segundo. Cada mensagem conta como uma requisição, então a 11ª requisição no mesmo segundo é bloqueada.

Como a API do Discord Aplica o Limite

O Discord usa um algoritmo de token bucket. Cada URL de webhook tem um bucket que recarrega a uma taxa de 5 tokens por segundo. Cada requisição consome um token. Se o bucket estiver vazio, a API rejeita a requisição e inclui o cabeçalho X-RateLimit-Reset com um timestamp Unix indicando quando o bucket terá um token disponível. O campo retry_after no corpo da resposta fornece o tempo de espera em milissegundos.

Passos para Prevenir Limites de Taxa do Webhook em Notificações em Rajada

O objetivo é espaçar suas requisições de webhook para que nunca excedam 5 por segundo. Os passos a seguir cobrem três métodos: reduzir a frequência de requisições, agrupar várias mensagens em uma única e implementar lógica de retry com backoff exponencial.

Método 1: Adicionar um Atraso Entre Cada Requisição de Webhook

Insira um atraso mínimo de 200 milissegundos entre chamadas consecutivas de webhook. Isso mantém sua taxa de requisições em 5 por segundo ou menos. A maioria das linguagens de programação suporta uma função sleep() ou delay().

1. Identifique o código que envia o webhook
   Localize a função ou script que chama a URL do webhook. Geralmente é uma requisição POST para https://discord.com/api/webhooks/{webhook.id}/{webhook.token}.
2. Insira um atraso de 200 ms antes de cada requisição
   Adicione await asyncio.sleep(0.2) em Python, Thread.sleep(200) em C#, setTimeout() em JavaScript ou sleep 0.2 em scripts shell.
3. Teste com uma rajada de 10 notificações
   Envie 10 mensagens de webhook em um loop. As primeiras 5 devem ter sucesso, as próximas 5 devem ter sucesso após o atraso. Verifique se nenhum erro 429 aparece nos logs.

Método 2: Agrupar Várias Mensagens em um Único Payload de Webhook

Os webhooks do Discord suportam o envio de múltiplos embeds em uma única requisição. Você pode combinar até 10 embeds por mensagem. Se suas entradas de log são apenas texto, você pode juntá-las com caracteres de nova linha em um único campo de conteúdo (até 2000 caracteres).

1. Colete todas as entradas de log em uma janela de tempo curta
   Em vez de enviar cada entrada de log imediatamente, armazene-as em uma lista ou fila. Use uma janela de 1 segundo para reunir as entradas.
2. Construa um único payload com múltiplos embeds
   Crie um payload JSON com um array embeds. Cada embed pode conter título, descrição e campos. Para logs de texto, use content com entradas separadas por nova linha.
3. Envie uma requisição de webhook por lote
   Após a janela de 1 segundo, envie o payload agrupado. Isso reduz o número de requisições de 10 para 1 para 10 entradas de log.

Método 3: Implementar Lógica de Retry com Backoff Exponencial

Quando o limite de taxa é atingido, seu código deve esperar antes de tentar novamente. O backoff exponencial aumenta o tempo de espera após cada falha consecutiva. Este é o método mais robusto para bots em produção.

1. Analise a resposta 429
   Leia o campo retry_after do corpo JSON. Se o campo estiver ausente, leia o cabeçalho X-RateLimit-Reset e calcule o tempo de espera como reset_time - current_time.
2. Aguarde pela duração especificada
   Use retry_after como tempo de espera inicial. Adicione um pequeno jitter aleatório, como 10% do tempo de espera, para evitar colisões de thundering herd.
3. Tente novamente a requisição
   Envie o mesmo payload do webhook novamente. Se a requisição for bem-sucedida, redefina o contador de backoff. Se falhar novamente, dobre o tempo de espera até um máximo de 10 segundos.
4. Registre as tentativas de retry
   Grave o número de tentativas e o tempo total de espera nos logs da aplicação para depuração.

Se o Limite de Taxa do Webhook do Discord Ainda Ocorrer Após a Correção Principal

Mesmo com atrasos e agrupamento, você ainda pode ver erros de limite de taxa em cenários específicos. As subseções a seguir abordam casos comuns.

Múltiplos Webhooks Compartilhando o Mesmo Canal

Se você tem vários webhooks postando no mesmo canal do Discord, cada URL de webhook tem seu próprio limite de taxa. No entanto, o limite global do Discord de 50 requisições por segundo por token de bot também se aplica. Se seu bot usa um único token para enviar para vários webhooks, o limite global pode ser atingido. A correção é usar um token de bot dedicado para cada webhook ou espaçar as requisições em todos os webhooks usando uma fila global com um intervalo mínimo de 20 ms entre quaisquer duas requisições.

Serviços de Log de Terceiros Enviando Rajadas

Serviços como Sentry, Datadog ou agregadores de log personalizados geralmente enviam notificações em rajadas. Verifique a configuração do serviço para uma opção de limite de taxa ou agrupamento. Por exemplo, no Sentry, você pode definir o “intervalo mínimo de notificação” para 1 segundo. No Datadog, você pode ativar o “agrupamento de alertas” para combinar vários alertas em uma única mensagem.

URL do Webhook Expirada ou Inválida Após Limite de Taxa

Se uma URL de webhook for excluída ou o token do bot for redefinido, o Discord retorna um erro 404, não 429. Sua lógica de retry deve distinguir entre erros 429 e 4xx. Para erros 404, pare de tentar e registre o webhook como inválido. Para erros 429, continue tentando com backoff.

Limite de Taxa do Webhook do Discord: Notificação em Rajada vs Notificação Agendada

Item	Notificação em Rajada	Notificação Agendada
Padrão de requisição	Múltiplas requisições em 1 segundo	Requisição única em intervalo fixo
Risco de limite de taxa	Alto – excede 5 requisições por segundo	Baixo – fica abaixo de 5 requisições por segundo
Causa principal	Eventos em lote (expulsão em massa, ações de filtro de spam)	Relatórios diários, cron jobs
Correção recomendada	Agrupar mensagens ou adicionar atraso de 200 ms	Nenhuma correção necessária, a menos que o intervalo seja inferior a 200 ms

Esta tabela mostra que notificações em rajada exigem estratégias ativas de limite de taxa, enquanto notificações agendadas raramente atingem o limite.

Agora você pode identificar por que seu webhook está atingindo o limite de taxa e aplicar a correção adequada. Use o atraso de 200 milissegundos para scripts simples, agrupe várias entradas de log em um único payload para bots de tráfego médio e implemente backoff exponencial com lógica de retry para sistemas de produção. Uma dica avançada: armazene o timestamp X-RateLimit-Reset e use-o para sincronizar várias instâncias do bot para que não tentem novamente ao mesmo tempo.