How to handle Discord rate limits without getting your bot blocked
Discord limits how fast a bot can make requests. Most of the time your library handles it quietly, and you never notice. When a bot misbehaves, such as hammering the API in a loop, the limits kick in hard, messages arrive late, and in the worst case the bot's address gets temporarily blocked. Knowing how the limits work lets you build a bot that behaves, and fix one that does not.
Two kinds of limits
HTTP rate limits apply to actions your bot takes through Discord's API: sending messages, editing roles, banning members, fetching data. Each kind of action has its own bucket, with a maximum number of requests in a time window. There is also a global cap on how many requests per second your bot can make, around 50.
Gateway limits apply to the live connection your bot holds open. They cap how many events your bot can send on that connection, and how often it can start a new session.
What a rate limit looks like
When your bot goes too fast, Discord answers with the status 429 Too Many Requests. The response includes how many seconds to wait, in a Retry-After value. A well-behaved library reads it, waits and then retries, so you only see a slight delay.
Your logs may show messages like "You are being rate limited". An occasional one is normal. A constant stream means your bot is doing too much, too fast.
Good habits
Let the library do its job. Do not write your own retry loop that ignores Retry-After, because it will hammer the API faster than the library would.
Avoid unnecessary requests. The best request is the one you never make:
- Use cached data. Libraries keep servers, channels and members in memory, so fetching them again from the API is rarely needed.
- Do not re-register slash commands at every start. Do it only when they change. See Slash commands vs prefix commands.
- Do not poll. If you need to know when something happens, subscribe to the event.
Slow down bulk actions. If a command changes many things, such as giving a role to every member or messaging a list of users, space the requests out, and show progress. Mass actions are what most often trigger limits, and mass direct messages can also get a bot flagged for spam.
Use the right endpoint. Bulk delete of messages is one request, and deleting messages one at a time is many. Libraries expose bulk methods for this.
Edit sparingly. Updating a message every second to show a counter uses up your limit quickly. Update every few seconds instead.
Be careful with reactions. They have a particularly tight limit. Adding many reactions in a row slows to a crawl.
The invalid request limit
Discord also watches for invalid requests, which are requests that fail with errors 401, 403 or 429. If your bot makes too many of those, about 10,000 in 10 minutes, the address your bot connects from can be blocked for a while. This usually happens when:
- A bot with a wrong or revoked token keeps retrying in a loop.
- Code keeps trying to do something it has no permission for.
- A rate-limited bot keeps sending requests regardless.
A bot caught in a crash loop with an invalid token is the classic example, and because many bots on a host can share one address, other bots may be affected too. Fixing invalid token errors on your Discord bot explains the loop and how to stop it. A sensible restart policy helps, as described in Keep your bot online.
Limits on connecting
Each time your bot starts, it opens a session, and Discord allows only a limited number per day, around 1,000 for a typical bot. A bot that crashes and restarts constantly can use that allowance up, after which it cannot connect until the limit resets. So treat repeated restarts as a serious problem, not a harmless one.
Reading your own logs
Look for signs of trouble:
| Sign | Likely cause |
|---|---|
| Frequent "rate limited" warnings | A loop, or a bulk action running too fast |
| Messages arrive late | Your bot is being throttled |
| Bot cannot connect for hours | You hit the session limit or an address block |
| Sudden burst of 403 errors | A permission change broke a feature, and the bot retries |
Logging and monitoring your Discord bot shows how to record these in a way you can search. If the log is hard to read, How to read your server logs has tips that apply to any bot.
If your bot is blocked
- Stop the bot, so that it does not make things worse.
- Find the cause in your logs, and fix it. Do not just restart.
- Wait. Blocks from invalid requests last for a limited time.
- Restart once and watch closely.
If you share a host with other bots, it may be someone else's code that caused it. Ask your host, as explained in How to open a support ticket on Discord.
Still stuck? Open a ticket on Discord - run /ticket in any channel, pick a department, and include your Server ID or Invoice ID so we can jump straight in.