Se o seu bot ou automação parar de enviar mensagens para um canal do Discord e você vir erros HTTP 429, você atingiu o limite de taxa do webhook do Discord. O Discord impõe um limite estrito de requisições por minuto para evitar spam e sobrecarga do servidor. Este artigo explica os números exatos do limite, como o Discord os calcula e o que você pode fazer para evitar ser bloqueado. Você aprenderá os limites específicos, como ler os cabeçalhos de resposta e como construir seu código para permanecer dentro da taxa permitida.
Principais Conclusões: Limites de Taxa do Webhook do Discord
- Limite padrão: 30 requisições a cada 60 segundos por URL de webhook.
- Cabeçalhos de limite: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e Retry-After indicam exatamente quando tentar novamente.
- Efeito do Server Boost: O Server Boost não aumenta o limite de taxa do webhook.
Como o Discord Aplica os Limites de Taxa do Webhook
O Discord aplica limites de taxa a todos os endpoints da API, incluindo webhooks. O objetivo é evitar que um único cliente sobrecarregue a plataforma. O limite é baseado no número de requisições enviadas em uma janela deslizante de 60 segundos. Se você exceder o limite, o Discord retorna uma resposta 429 Too Many Requests. A resposta inclui cabeçalhos que informam quanto tempo esperar antes de tentar novamente.
O limite padrão para webhooks é de 30 requisições a cada 60 segundos por URL de webhook. Esse limite se aplica a todos os tipos de operações de webhook: envio de mensagens, edição de mensagens e exclusão de mensagens. Cada URL de webhook tem seu próprio contador independente. Enviar várias mensagens em paralelo para a mesma URL de webhook ainda conta para o mesmo bucket.
O Discord usa internamente um algoritmo de token bucket. Cada URL de webhook começa com um bucket de 30 tokens. Cada requisição consome um token. Os tokens são regenerados a uma taxa de um token a cada dois segundos. Se o bucket esvaziar, novas requisições são rejeitadas até que os tokens sejam regenerados.
Cabeçalhos de Limite de Taxa Explicados
Quando você envia uma requisição para um webhook do Discord, a resposta inclui estes cabeçalhos:
- X-RateLimit-Limit: O número máximo de requisições permitidas na janela atual. Para webhooks, é sempre 30.
- X-RateLimit-Remaining: Quantas requisições você ainda pode enviar na janela atual antes de atingir o limite.
- X-RateLimit-Reset: Um timestamp Unix (em segundos) indicando quando a janela de limite é redefinida e o contador restante volta ao limite.
- Retry-After: O número de segundos que você deve esperar antes de enviar outra requisição. Este cabeçalho aparece apenas quando você recebe uma resposta 429.
Você deve analisar esses cabeçalhos em seu código e aguardar o tempo especificado antes de tentar novamente. Ignorar o valor Retry-After causará erros 429 repetidos e pode levar ao bloqueio temporário do seu webhook.
Passos para Permanecer Dentro do Limite de Taxa do Webhook
Para evitar atingir o limite de taxa, você deve implementar uma limitação adequada de requisições em seu código. Siga estes passos para construir um envio de webhook seguro.
- Verifique os cabeçalhos de limite após cada requisição
Após cada chamada de webhook, leia os cabeçalhos X-RateLimit-Remaining e X-RateLimit-Reset. Armazene o timestamp de reset localmente. Se remaining for 0, calcule o tempo de espera subtraindo o tempo atual do timestamp de reset. Adicione um pequeno buffer de 0,5 segundos para compensar diferenças de relógio. - Aguarde antes de enviar a próxima requisição
Use um timer ou função de pausa para interromper a execução pelo tempo de espera calculado. Não envie nenhuma requisição para a mesma URL de webhook durante esse período. Se você enviar várias requisições em paralelo, use um sistema de fila que processe uma requisição por vez. - Lide com erros 429 de forma adequada
Se você receber uma resposta 429, leia o cabeçalho Retry-After e aguarde esse número de segundos antes de tentar a mesma requisição novamente. Não tente imediatamente sem esperar. Registre o erro para fins de depuração. - Use uma única URL de webhook por canal, se possível
Evite criar vários webhooks para o mesmo canal. Cada URL de webhook tem seu próprio limite de taxa, mas o canal em si também tem limites. Usar uma única URL simplifica o rastreamento do limite. - Agrupe mensagens quando precisar enviar muitas de uma vez
Se você precisar enviar várias mensagens em rápida sucessão, combine-as em uma única mensagem usando embeds ou uma abordagem de conteúdo em lote. O Discord permite até 10 embeds em uma mensagem de webhook. Isso reduz o número de requisições.
O que Acontece Quando Você Excede o Limite de Taxa
Exceder o limite de taxa dispara uma resposta 429. O cabeçalho Retry-After informa quantos segundos esperar. Se você continuar enviando requisições sem esperar, o Discord pode bloquear temporariamente sua URL de webhook por um período mais longo. O bloqueio pode durar de alguns segundos a vários minutos, dependendo da gravidade da violação. Abusos repetidos podem levar à suspensão permanente do webhook.
Webhook Desabilitado Após Múltiplos Erros 429
Após várias violações consecutivas do limite, o Discord pode desabilitar completamente o webhook. O webhook parará de funcionar até que você o reative nas configurações do servidor do Discord. Para reativar, vá em Configurações do Servidor > Integrações > Webhooks, clique no webhook e alterne o status. Você deve então corrigir seu código para evitar novas violações.
Limite Global vs. Limite do Webhook
O Discord também tem um limite global para todas as requisições da API, incluindo webhooks. O limite global é de 50 requisições por segundo em todos os endpoints. Se você exceder o limite global, receberá uma resposta 429 com um cabeçalho Retry-After. O limite global é separado do limite por webhook. Você deve respeitar ambos os limites.
| Item | Limite do Webhook | Limite Global |
|---|---|---|
| Escopo | Por URL de webhook | Todas as requisições da API do seu aplicativo |
| Requisições por janela | 30 a cada 60 segundos | 50 por segundo |
| Cabeçalhos | X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After | X-RateLimit-Global, Retry-After |
| Consequência da violação | Bloqueio por webhook | Bloqueio global de IP ou token |
Erros Comuns ao Lidar com o Limite de Taxa
Não Ler os Cabeçalhos em Respostas Bem-Sucedidas
Muitos desenvolvedores só verificam os cabeçalhos em erros 429. Isso é um erro. Os cabeçalhos de limite estão presentes em todas as respostas, incluindo 200 OK. Ao lê-los em cada resposta, você pode prever quando atingirá o limite e desacelerar antes de obter um 429.
Não Adicionar um Buffer ao Tempo de Espera
O timestamp X-RateLimit-Reset é definido pelo relógio do servidor do Discord. Seu relógio local pode diferir em alguns segundos. Se você enviar uma requisição exatamente no momento do reset, ainda poderá receber um 429 porque a janela do Discord ainda não fechou. Adicione um buffer de 0,5 segundos ao tempo de espera calculado para evitar esse caso extremo.
Usar Múltiplos Webhooks para o Mesmo Canal
Criar várias URLs de webhook para o mesmo canal não aumenta seu limite de taxa efetivo. Cada URL tem seu próprio limite de 30 requisições, mas o canal em si tem um limite de quantas mensagens podem ser enviadas por minuto. Usar várias URLs pode acionar outros limites de taxa. Mantenha um webhook por canal.
Conclusão
Os limites de taxa do webhook do Discord são de 30 requisições a cada 60 segundos por URL de webhook. Você pode evitar erros 429 lendo os cabeçalhos X-RateLimit-Remaining e X-RateLimit-Reset após cada requisição e aguardando o tempo adequado. Sempre adicione um pequeno buffer ao tempo de espera para compensar diferenças de relógio. Para uso de alto volume, agrupe mensagens usando embeds para reduzir o número total de requisições. Implemente um sistema de fila adequado que processe requisições uma de cada vez e respeite o cabeçalho Retry-After.