Discord Webhook 429 Muitas Requisições: Estratégia de Backoff

Quando você envia requisições de webhook para o Discord e recebe um erro 429, seu bot ou automação está sendo limitado por taxa. O Discord impõe limites de taxa rigorosos para proteger sua API de abuso e sobrecarga. Uma resposta 429 significa que você excedeu o número permitido de requisições em uma janela de tempo específica. Este artigo explica o que causa o erro 429, como funciona a estratégia de backoff do Discord e como implementar um mecanismo de repetição correto no seu código.

Você aprenderá quais headers ler, o valor de retry-after a respeitar e como construir uma estratégia de backoff que mantenha sua integração de webhook funcionando sem ser banida. Também abordamos erros comuns que disparam repetidos erros 429 e como evitá-los.

Por que o Discord Retorna 429 para Requisições de Webhook

O Discord usa limites de taxa para proteger sua API de tráfego excessivo. Cada webhook tem um limite de taxa global de 30 requisições por 60 segundos. Este limite se aplica à URL do webhook em si, não por canal ou servidor. Quando seu código envia requisições mais rápido que este limite, o Discord responde com o status HTTP 429 e um corpo JSON contendo um campo retry_after medido em segundos.

O limite de taxa é calculado usando um algoritmo de janela deslizante. O Discord rastreia o número de requisições nos últimos 60 segundos. Se a contagem exceder 30, a resposta 429 é acionada. O valor retry_after informa quantos segundos esperar até que a janela seja redefinida e você possa enviar outra requisição com segurança.

Um equívoco comum é que os limites de taxa se aplicam por canal ou por servidor. Eles se aplicam por URL de webhook. Se você tem vários bots ou scripts postando no mesmo webhook, eles compartilham o mesmo bucket de limite de taxa. Um erro 429 de um script significa que todos os scripts que usam aquele webhook devem esperar.

Headers de Limite de Taxa na Resposta 429

Quando o Discord retorna um 429, a resposta inclui vários headers que ajudam a implementar uma estratégia de backoff correta:

• Retry-After: Um número inteiro de segundos que você deve esperar antes de tentar novamente. Este é o valor mais direto a usar.
• X-RateLimit-Global: Definido como true quando o limite de taxa é global, significando que você deve parar todas as requisições para todos os endpoints, não apenas este webhook.
• X-RateLimit-Reset: Um timestamp Unix (em segundos) indicando quando a janela de limite de taxa é redefinida. Use isso se precisar calcular tempos de espera precisos.
• X-RateLimit-Reset-After: O tempo restante em segundos até a janela ser redefinida. Corresponde ao Retry-After, mas é fornecido como um header separado por conveniência.

Passos para Implementar uma Estratégia de Backoff Adequada para Erros 429

Siga estes passos para construir um mecanismo de repetição que respeite os limites de taxa do Discord e evite que sua integração seja bloqueada temporária ou permanentemente.

1. Verifique o Código de Status HTTP
   Após enviar uma requisição de webhook, inspecione o código de status da resposta. Se for 429, prossiga para o próximo passo. Se for 200 ou 204, a requisição foi bem-sucedida e nenhuma ação adicional é necessária.
2. Leia o Header Retry-After
   Extraia o header Retry-After da resposta. Este header contém um inteiro representando o número de segundos a esperar. Se o header estiver ausente, recorra ao campo retry_after no corpo da resposta JSON.
3. Aguarde a Duração Especificada
   Pause a execução pelo número exato de segundos indicado pelo Retry-After. Use uma função de sleep ou delay na sua linguagem de programação. Não encurte a espera — fazer isso resultará em outro 429 e pode levar a um banimento temporário de IP.
4. Repita a Requisição
   Após o período de espera terminar, reenvie o mesmo payload do webhook. Se a resposta for novamente 429, repita os passos 1 a 4. Para erros 429 consecutivos, implemente backoff exponencial multiplicando o tempo de espera por 2 a cada repetição.
5. Adicione Jitter para Evitar Thundering Herd
   Se várias instâncias do seu código receberem um 429 ao mesmo tempo, todas tentarão novamente simultaneamente após o mesmo período de espera. Isso pode causar outro 429. Adicione jitter aleatório — um valor aleatório entre 0 e 1 segundo — a cada tempo de espera para distribuir as tentativas de repetição.
6. Defina um Número Máximo de Repetições
   Não repita indefinidamente. Defina um limite máximo de repetições, como 5 tentativas. Após isso, registre o erro e pare de tentar. Isso evita que seu código fique preso em um loop infinito se a API do Discord estiver fora do ar ou se a URL do webhook for inválida.

Exemplo de Pseudocódigo para Estratégia de Backoff

max_retries = 5
retry_count = 0
base_wait = 1

while retry_count < max_retries:
    response = send_webhook(payload)
    if response.status == 200:
        break
    if response.status == 429:
        retry_after = response.headers['Retry-After']
        wait_time = retry_after + (base_wait  (2  retry_count))
        jitter = random(0, 1)
        sleep(wait_time + jitter)
        retry_count += 1
    else:
        log_error(response)
        break

Se o Discord Ainda Retornar 429 Após Implementar o Backoff

Você Está Enviando Muitas Requisições por Segundo

Mesmo com backoff, enviar rajadas de requisições em rápida sucessão pode acionar 429. O limite de taxa do Discord é de 30 requisições por 60 segundos, o que dá uma média de uma requisição a cada 2 segundos. Se você enviar 10 requisições em um segundo, as primeiras podem ter sucesso, mas o restante receberá 429. Para evitar isso, implemente um limitador de taxa no seu código que rastreie o número de requisições enviadas nos últimos 60 segundos e atrase o envio se o limite estiver próximo.

Sua URL de Webhook é Compartilhada por Vários Processos

Se vários servidores ou scripts usam a mesma URL de webhook, cada um tem seus próprios contadores de limite de taxa. O limite de taxa do Discord se aplica por URL de webhook, não por endereço IP. O tráfego combinado de todos os processos pode exceder o limite. A solução é usar um único processo coordenador que enfileira todas as requisições de webhook e as envia a uma taxa controlada. Alternativamente, crie webhooks separados para diferentes funções e distribua o tráfego entre eles.

Você Está Ignorando Limites de Taxa Globais

Quando o header X-RateLimit-Global é true, você deve parar todas as requisições para todos os endpoints da API do Discord, não apenas o endpoint do webhook. Isso é raro, mas pode acontecer se seu bot estiver abusando da API. Se você receber um 429 global, pause toda a atividade da API pela duração especificada no Retry-After. Continuar fazendo outras chamadas de API resultará em um banimento mais longo.

Tipos de Limite de Taxa do Discord: Global vs Por Webhook

Item	Limite de Taxa Global	Limite de Taxa Por Webhook
Escopo	Todos os endpoints da API para seu bot ou aplicação	Apenas a URL específica do webhook
Limite	Varia por endpoint, tipicamente 50 requisições por segundo	30 requisições por 60 segundos
Acionado por	Requisições excessivas em qualquer endpoint	Requisições excessivas a uma URL de webhook
Indicador no header	X-RateLimit-Global: true	X-RateLimit-Global: false ou ausente
Ação de backoff	Parar todas as requisições à API pelo período de espera	Parar apenas requisições àquela URL de webhook

Implementar a estratégia de backoff correta para erros 429 do Discord webhook mantém sua integração estável e evita banimentos temporários. Sempre leia o header Retry-After, use backoff exponencial com jitter e defina um número máximo de repetições. Se continuar vendo erros 429, verifique sua taxa de requisições por segundo, consolide o uso compartilhado de webhooks e respeite os limites de taxa globais. Para controle avançado, considere usar um sistema de fila que armazene requisições em buffer e as envie em um intervalo fixo abaixo do limite de taxa.