Discord caps how fast any bot can call its API. Cross the line and you get a 429 response telling you to wait. Most of the time your library absorbs this quietly and you never notice — the trouble starts when your code fights the limit instead of respecting it. This guide explains what's happening, what your library already does for you, and the one mistake that gets a bot's connection temporarily banned.
| At a glance | |
|---|---|
| The signal | HTTP 429 Too Many Requests with a retry_after wait time |
| Good news | discord.js and discord.py queue and wait for you automatically |
| The danger | Tight loops that hammer the API — and repeated invalid requests |
What a rate limit is
Discord's API allows only so many requests in a window. Send too many too fast and Discord replies 429, with a retry_after value — how many seconds to hold off before trying again. Limits are per-route (editing this channel, sending to that one) with separate "buckets," plus a global ceiling of roughly 50 requests per second across everything your bot does.
You don't normally see any of this, because your library handles it.
Your library already does the right thing
Both major libraries have an HTTP layer that queues your requests and respects 429s on its own:
- discord.js routes every API call through a REST manager that tracks each bucket, spaces requests out, and waits out a 429 before retrying. It can emit a
rateLimitedevent so you can observe it, but you don't have to write the waiting logic. - discord.py does the same inside its HTTP client — on a 429 it sleeps for
retry_afterand retries, and logs a line like "We are being rate limited" so you can see it in the console.
The practical takeaway: don't write your own retry/sleep code around normal API calls. The library's queue is smarter than a hand-rolled loop, and adding your own retries on top usually makes congestion worse.
What NOT to do
Rate-limit pain is almost always self-inflicted — code that asks for far more than it needs:
- Editing a message in a tight loop. A live countdown or progress bar that edits every few milliseconds will flood the bucket. Update once a second or slower, not as fast as the loop spins.
- Sending in a bare
forloop. Firing hundreds of messages with no pacing fills the queue and delays everything else your bot does. Batch where you can. - Reacting/looping over big lists without pause. Adding many reactions, or touching every member, back-to-back is a burst the bucket won't allow.
- Retrying failures immediately. If a call fails, spinning on it just multiplies the load.
💡 Tip: Prefer the batch tools Discord gives you — bulk-delete for purging messages, a single edited embed instead of many messages, one status update instead of a rotation that spins too fast.
The invalid-request limit — the honest warning
There's a second, harsher limit that has nothing to do with speed. Discord counts invalid requests — ones that come back 401 (bad auth), 403 (forbidden), or 429 — and if a bot produces too many in a short window (Discord's documented threshold is 10,000 in 10 minutes), the connection gets temporarily banned at the network edge for about an hour.
This is the one to take seriously, because it's easy to trigger by accident:
- A bad-token retry loop — reconnecting over and over with an invalid token racks up 401s fast. (If the console shows
TokenInvalidorLoginFailure, fix the token; don't let it retry. See My bot shows offline.) - Hammering an endpoint you lack permission for — repeated 403s from an action the bot's role can't perform.
The fix is never to wait it out and hope — it's to stop the bot, fix the loop or the token/permission, and only then start it again. Restarting into the same broken loop just restarts the ban clock.
⚠️ Heads up: During one of these temporary bans, your bot can't reach Discord at all — it'll look offline even though your Falix server is running fine. Read the console: a wall of repeated 401/403/429 lines is the tell.
When you actually hit normal limits
For ordinary rate limits, the answer is patience and pacing, not code gymnastics: let the library queue, slow down the chattiest actions, and batch. If your bot is genuinely large enough to bump the global limit routinely, that's a scaling conversation — but for the vast majority of bots, fixing one runaway loop solves it.
Everything about the limits themselves is standard Discord behaviour — the official discord.js and discord.py documentation, and Discord's own developer docs, cover the exact numbers and headers.