Fix Discord Webhook Rate Limit Hit on Burst Notifications From Logs

You see the error message “You are being rate limited” in your server logs after sending multiple notifications from a bot or integration. This happens when your webhook sends more than 5 requests per second to Discord’s API. Discord enforces this limit to prevent spam and protect server performance. This article explains why burst notifications trigger the rate limit and provides step-by-step fixes to reduce request frequency and add retry logic.

Why Discord Webhooks Rate Limit Burst Notifications

Discord’s webhook API enforces a rate limit of 5 requests per second per webhook URL. This limit is measured on a rolling 1-second window. When your logging bot or integration sends multiple notifications in rapid succession, it exceeds this threshold. The API returns an HTTP 429 status code with a JSON body containing the error message “You are being rate limited” and a retry_after field in milliseconds.

The burst occurs most often when a single event triggers multiple log entries. For example, a server moderation action that kicks 10 users at once might attempt to send 10 separate webhook messages within a fraction of a second. Each message counts as one request, so the 11th request in the same second is blocked.

How Discord’s API Enforces the Limit

Discord uses a token bucket algorithm. Each webhook URL has a bucket that refills at a rate of 5 tokens per second. Each request consumes one token. If the bucket is empty, the API rejects the request and includes the X-RateLimit-Reset header with a Unix timestamp indicating when the bucket will have a token available. The retry_after field in the response body gives the wait time in milliseconds.

Steps to Prevent Webhook Rate Limit Hits on Burst Notifications

The goal is to spread out your webhook requests so they never exceed 5 per second. The following steps cover three methods: reducing request frequency, batching multiple messages into one, and implementing retry logic with exponential backoff.

Method 1: Add a Delay Between Each Webhook Request

Insert a minimum 200-millisecond delay between consecutive webhook calls. This keeps your request rate at 5 per second or less. Most programming languages support a sleep() or delay() function.

1. Identify the code that sends the webhook
   Locate the function or script that calls the webhook URL. It is typically a POST request to https://discord.com/api/webhooks/{webhook.id}/{webhook.token}.
2. Insert a 200-ms delay before each request
   Add await asyncio.sleep(0.2) in Python, Thread.sleep(200) in C#, setTimeout() in JavaScript, or sleep 0.2 in shell scripts.
3. Test with a burst of 10 notifications
   Send 10 webhook messages in a loop. The first 5 should succeed, the next 5 should succeed after the delay. Verify no 429 errors appear in your logs.

Method 2: Batch Multiple Messages Into One Webhook Payload

Discord webhooks support sending multiple embeds in a single request. You can combine up to 10 embeds per message. If your log entries are text-only, you can join them with newline characters into a single content field (up to 2000 characters).

1. Collect all log entries for a short time window
   Instead of sending each log entry immediately, store them in a list or queue. Use a 1-second window to gather entries.
2. Build a single payload with multiple embeds
   Create a JSON payload with an embeds array. Each embed can contain a title, description, and fields. For text-only logs, use content with newline-separated entries.
3. Send one webhook request per batch
   After the 1-second window, send the batched payload. This reduces the request count from 10 to 1 for 10 log entries.

Method 3: Implement Retry Logic With Exponential Backoff

When a rate limit is hit, your code must wait before retrying. Exponential backoff increases the wait time after each consecutive failure. This is the most robust method for production bots.

1. Parse the 429 response
   Read the retry_after field from the JSON body. If the field is missing, read the X-RateLimit-Reset header and calculate the wait time as reset_time - current_time.
2. Wait for the specified duration
   Use retry_after as the initial wait time. Add a small random jitter, such as 10% of the wait time, to avoid thundering herd collisions.
3. Retry the request
   Send the same webhook payload again. If the request succeeds, reset the backoff counter. If it fails again, double the wait time up to a maximum of 10 seconds.
4. Log the retry attempts
   Record the number of retries and the total wait time in your application logs for debugging.

If Discord Webhook Rate Limit Still Occurs After the Main Fix

Even with delays and batching, you may still see rate limit errors in specific scenarios. The following subsections address common edge cases.

Multiple Webhooks Sharing the Same Channel

If you have multiple webhooks posting to the same Discord channel, each webhook URL has its own rate limit. However, Discord’s global rate limit of 50 requests per second per bot token also applies. If your bot uses a single token to send to multiple webhooks, the global limit can be hit. The fix is to use a dedicated bot token for each webhook or to stagger requests across all webhooks using a global queue with a 20-ms minimum interval between any two requests.

Third-Party Logging Services Sending Bursts

Services like Sentry, Datadog, or custom log aggregators often send notifications in bursts. Check the service’s configuration for a rate limit setting or a batching option. For example, in Sentry, you can set the “minimum notification interval” to 1 second. In Datadog, you can enable “alert grouping” to combine multiple alerts into one message.

Webhook URL Expired or Invalid After Rate Limit

If a webhook URL is deleted or the bot’s token is reset, Discord returns a 404 error, not a 429. Your retry logic should distinguish between 429 and 4xx errors. For 404 errors, stop retrying and log the webhook as invalid. For 429 errors, continue retrying with backoff.

Discord Webhook Rate Limit: Burst Notification vs Scheduled Notification

Item	Burst Notification	Scheduled Notification
Request pattern	Multiple requests within 1 second	Single request at a fixed interval
Rate limit risk	High – exceeds 5 requests per second	Low – stays under 5 requests per second
Primary cause	Batch events (mass kick, spam filter actions)	Daily reports, cron jobs
Recommended fix	Batch messages or add 200-ms delay	No fix needed unless interval is under 200 ms

This table shows that burst notifications require active rate limiting strategies, while scheduled notifications rarely hit the limit.

You can now identify why your webhook is hitting the rate limit and apply the appropriate fix. Use the 200-millisecond delay for simple scripts, batch multiple log entries into a single payload for medium-traffic bots, and implement exponential backoff with retry logic for production systems. An advanced tip: store the X-RateLimit-Reset timestamp and use it to synchronize multiple bot instances so they do not all retry at the same time.