If your bot or automation stops sending messages to a Discord channel and you see HTTP 429 errors, you have hit the Discord webhook rate limit. Discord enforces a strict requests-per-minute threshold to prevent spam and server overload. This article explains the exact rate limit numbers, how Discord calculates them, and what you can do to avoid being blocked. You will learn the specific limits, how to read response headers, and how to build your code to stay within the allowed rate.
Key Takeaways: Discord Webhook Rate Limits
- Default rate limit: 30 requests per 60 seconds per webhook URL.
- Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After tell you exactly when to retry.
- Server Boost effect: Server Boost does not increase the webhook rate limit.
How Discord Enforces Webhook Rate Limits
Discord applies rate limits to every API endpoint, including webhooks. The purpose is to prevent a single client from overwhelming the platform. The limit is based on the number of requests sent within a sliding 60-second window. If you exceed the limit, Discord returns a 429 Too Many Requests response. The response includes headers that tell you how long to wait before retrying.
The default rate limit for webhooks is 30 requests per 60 seconds per webhook URL. This limit applies to all types of webhook operations: sending messages, editing messages, and deleting messages. Each webhook URL has its own independent counter. Sending multiple messages in parallel to the same webhook URL still counts against the same bucket.
Discord uses a token bucket algorithm internally. Every webhook URL starts with a bucket of 30 tokens. Each request consumes one token. Tokens regenerate at a rate of one token every two seconds. If the bucket empties, new requests are rejected until tokens regenerate.
Rate Limit Headers Explained
When you send a request to a Discord webhook, the response includes these headers:
- X-RateLimit-Limit: The maximum number of requests allowed in the current window. For webhooks, this is always 30.
- X-RateLimit-Remaining: How many requests you can still send in the current window before hitting the limit.
- X-RateLimit-Reset: A Unix timestamp (in seconds) when the rate limit window resets and the remaining count goes back to the limit.
- Retry-After: The number of seconds you must wait before sending another request. This header appears only when you receive a 429 response.
You must parse these headers in your code and wait the specified time before retrying. Ignoring the Retry-After value will cause repeated 429 errors and may lead to your webhook being temporarily blocked.
Steps to Stay Within the Webhook Rate Limit
To avoid hitting the rate limit, you must implement proper request throttling in your code. Follow these steps to build a safe webhook sender.
- Check the rate limit headers after every request
After each webhook call, read the X-RateLimit-Remaining and X-RateLimit-Reset headers. Store the reset timestamp locally. If remaining is 0, calculate the wait time by subtracting the current time from the reset timestamp. Add a small buffer of 0.5 seconds to account for clock drift. - Wait before sending the next request
Use a timer or sleep function to pause execution for the calculated wait time. Do not send any requests to the same webhook URL during that period. If you send multiple requests in parallel, use a queue system that processes one request at a time. - Handle 429 errors gracefully
If you receive a 429 response, read the Retry-After header and wait that many seconds before retrying the same request. Do not retry immediately without waiting. Log the error for debugging purposes. - Use a single webhook URL for each channel if possible
Avoid creating multiple webhooks for the same channel. Each webhook URL has its own rate limit, but the channel itself also has limits. Using one URL simplifies rate limit tracking. - Batch messages when you need to send many at once
If you need to send multiple messages in quick succession, combine them into a single message using embeds or a bulk content approach. Discord allows up to 10 embeds in one webhook message. This reduces the number of requests.
What Happens When You Exceed the Rate Limit
Exceeding the rate limit triggers a 429 response. The Retry-After header tells you how many seconds to wait. If you continue to send requests without waiting, Discord may temporarily block your webhook URL for a longer period. The block can last from a few seconds to several minutes depending on the severity of the violation. Repeated abuse may lead to permanent suspension of the webhook.
Webhook Disabled After Multiple 429 Errors
After several consecutive rate limit violations, Discord may disable the webhook entirely. The webhook will stop working until you re-enable it from the Discord server settings. To re-enable, go to Server Settings > Integrations > Webhooks, click on the webhook, and toggle the status. You must then fix your code to prevent further violations.
Global Rate Limit vs Webhook Rate Limit
Discord also has a global rate limit for all API requests, including webhooks. The global limit is 50 requests per second across all endpoints. If you exceed the global limit, you receive a 429 response with a Retry-After header. The global limit is separate from the per-webhook limit. You must respect both limits.
| Item | Webhook Rate Limit | Global Rate Limit |
|---|---|---|
| Scope | Per webhook URL | All API requests from your application |
| Requests per window | 30 per 60 seconds | 50 per second |
| Headers | X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After | X-RateLimit-Global, Retry-After |
| Consequence of violation | Per-webhook block | Global IP or token block |
Common Mistakes When Handling the Rate Limit
Not Reading Headers on Successful Responses
Many developers only check headers on 429 errors. This is a mistake. The rate limit headers are present on every response, including 200 OK. By reading them on every response, you can predict when you will hit the limit and slow down before getting a 429.
Not Adding a Buffer to the Wait Time
The X-RateLimit-Reset timestamp is set by Discord’s server clock. Your local clock may differ by a few seconds. If you send a request exactly at the reset time, you may still receive a 429 because Discord’s window has not yet closed. Add a 0.5-second buffer to the calculated wait time to avoid this edge case.
Using Multiple Webhooks for the Same Channel
Creating multiple webhook URLs for the same channel does not increase your effective rate limit. Each URL has its own 30-request limit, but the channel itself has a limit on how many messages can be sent per minute. Using multiple URLs can cause other rate limits to trigger. Stick to one webhook per channel.
Conclusion
Discord webhook rate limits are set at 30 requests per 60 seconds per webhook URL. You can avoid 429 errors by reading the X-RateLimit-Remaining and X-RateLimit-Reset headers after every request and waiting the appropriate amount of time. Always add a small buffer to the wait time to account for clock differences. For high-volume use, batch messages using embeds to reduce the total number of requests. Implement a proper queue system that processes requests one at a time and respects the Retry-After header.