Menu
Discord bot API rate limits and how to handle a 429
Discord limits each route separately, caps every bot at 50 requests a second, and blocks IPs that keep sending bad requests. This is how each one works and how to write code that never trips them.
Step 0Before you start: create a free VaultCord account
Do this before you write any code. A free VaultCord account gives you a working verification flow to compare your own against, plus a fallback if your bot goes down.
- Your own branded bot: 1 on Free, 3 on Premium, unlimited on Plus, online 24/7.
- Unlimited restorable members on every plan, Free included. Pulls run at one member every 0.98 seconds, on every plan.
- Developer API to pull members with code (Plus), plus a Resell Members API. Plus is $9.97/mo, or $3.83/mo billed yearly.
- An MCP server, so Claude or another MCP client can run your account, and the iOS and Android apps.
On this page
The four limits that matter
Most "my bot stopped working" reports after a burst of activity come down to one of these. They stack: a request has to pass all of them.
| Limit | Size | Scope |
|---|---|---|
| Per-route bucket | Varies, read X-RateLimit-Limit | Per route, method and top-level resource (channel, guild or webhook) |
| Global | 50 requests per second | Per bot. Without an Authorization header it applies per IP |
| Invalid requests | 10,000 per 10 minutes | Per IP. Counts 401, 403 and 429 responses |
| Gateway sends | 120 events per 60 seconds | Per Gateway connection. Going over disconnects you |
The top-level resource rule is useful. Hitting the limit on /channels/1234/messages does not slow down /channels/9876/messages, because the channel ID is part of the bucket. Spreading work across channels or guilds spreads it across buckets too.
The Gateway has two more caps worth knowing if you restart often: identifying is limited by max_concurrency (identify requests per 5 seconds), and a bot gets 1000 IDENTIFY calls per 24 hours.
Reading the headers
Every REST response carries the state of the bucket it used. Discord asks you to rely on these rather than numbers you found in a forum post.
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in this bucket |
X-RateLimit-Remaining | Requests left before you get a 429 |
X-RateLimit-Reset | Epoch time in seconds when the bucket resets |
X-RateLimit-Reset-After | Seconds until reset, can include decimals |
X-RateLimit-Bucket | A unique ID for the bucket. Routes that share a limit share this value |
X-RateLimit-Global | Only on a 429, and only if you hit the global limit |
X-RateLimit-Scope | Only on a 429: user, global or shared |
A simple rule that works: key your queue by X-RateLimit-Bucket plus the top-level resource ID. When Remaining reaches 0, hold the next request for that key until Reset-After passes.
What a 429 looks like
The body tells you how long to wait and whether the whole bot is limited or just this bucket.
HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Scope: user
X-RateLimit-Bucket: abcd1234
{
"message": "You are being rate limited.",
"retry_after": 0.64,
"global": false
}retry_after: seconds to wait, as a float.global:truemeans stop everything, not just this route.code: sometimes present, for specific limits.X-RateLimit-Scope: sharedmeans you hit a per-resource limit rather than your own. These 429s do not count toward the invalid request limit.
Handling it in code
If you call the API directly, wait for retry_after and try again. If you use a library, check how it queues requests before adding your own retry loop on top, or you will retry twice:
async function discord(path, init = {}, tries = 5) {
for (let i = 0; i < tries; i++) {
const res = await fetch(`https://discord.com/api/v10${path}`, {
...init,
headers: {
Authorization: `Bot ${process.env.BOT_TOKEN}`,
"User-Agent": "DiscordBot (https://example.com, 1.0)",
...init.headers,
},
})
if (res.status !== 429) return res
const body = await res.json()
const wait = (body.retry_after ?? (Number(res.headers.get("Retry-After")) || 1)) * 1000
await new Promise((r) => setTimeout(r, wait))
}
throw new Error("still rate limited after retries")
}import os
import time
import requests
def discord(method, path, tries=5, **kw):
headers = {
"Authorization": f"Bot {os.environ['BOT_TOKEN']}",
"User-Agent": "DiscordBot (https://example.com, 1.0)",
}
for _ in range(tries):
r = requests.request(method, f"https://discord.com/api/v10{path}", headers=headers, **kw)
if r.status_code != 429:
return r
wait = r.json().get("retry_after") or float(r.headers.get("Retry-After", 1))
time.sleep(wait)
raise RuntimeError("still rate limited after retries")Retrying is the fallback, not the plan
Every 429 you receive counts toward the invalid request limit unless its scope is shared. Read X-RateLimit-Remaining and slow down before Discord has to tell you.
Avoiding the invalid request ban
If an IP sends 10,000 requests in 10 minutes that come back 401, 403 or 429, Discord restricts that IP from the API for a while. On shared hosting this can take out every bot on the machine. Check these:
- Stop on 401. A bad or reset token will never start working by retrying.
- Stop on 403 for that resource. The bot lacks a permission or was removed; fix that instead of looping.
- Respect
retry_afteron every 429. - Send a
User-AgentlikeDiscordBot (https://example.com, 1.0). Requests without a valid one can be blocked. - Never hard-code limits. Parse the headers on every response.
Rate limits when adding members
Restoring members with OAuth2 guilds.join means one PUT /guilds/{guild.id}/members/{user.id} per person, all against the same guild. That puts every request in one bucket, so pacing matters more here than almost anywhere else. Failed tokens make it worse: an expired token returns an error you should not retry.
VaultCord handles this for you. It pulls one member every 0.98 seconds, on every plan. You also get a custom join delay between pulls to reduce Discord rate limits, and proxied requests on every plan. Instant deauthorization detection keeps member records in sync, so it does not waste requests on people who removed the app. Developer API to pull members with code (Plus), plus a Resell Members API. Open the dashboard to try a pull on the Free plan.
Related: Discord API overview and OAuth2 scopes.
FAQ
What is the Discord bot API rate limit?
There is no single number. Each route has its own bucket, reported in the X-RateLimit headers. On top of that, a bot can make up to 50 requests per second across all routes (the global limit), and any IP that sends 10,000 invalid requests in 10 minutes is temporarily blocked.
How long does a Discord rate limit last?
As long as the response says. A 429 includes retry_after in the JSON body (seconds, can be a decimal) and a Retry-After header. Wait that long and retry. Per-route buckets also tell you X-RateLimit-Reset-After before you ever hit a 429.
Does Discord rate limit interactions?
Interaction endpoints, such as responding to a slash command, are not bound by the bot's global rate limit. Per-route limits still apply.
Why did my bot get a Cloudflare ban?
Usually a loop that keeps sending requests that fail with 401, 403 or 429. Discord counts those as invalid requests, and 10,000 of them in 10 minutes gets the IP restricted for a while. 429s with X-RateLimit-Scope: shared do not count.
Should I hard-code Discord's rate limits?
No. Discord's docs say to parse the response headers instead, because limits can change and differ by route.
Last updated on November 19, 2026