GuidesOnly show guides for your app
GuidesGuidesWhat a 429 and retry_after mean, why discord.js and discord.py already handle them for you, the loops that get you in trouble, and the invalid-request limit that can temporarily ban your bot's connection.
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 |
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.
Both major libraries have an HTTP layer that queues your requests and respects 429s on its own:
rateLimited event so you can observe it, but you don't have to write the waiting logic.retry_after and 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.
Rate-limit pain is almost always self-inflicted — code that asks for far more than it needs:
for loop. Firing hundreds of messages with no pacing fills the queue and delays everything else your bot does. Batch where you can.💡 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.
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:
TokenInvalid or LoginFailure, fix the token; don't let it retry. See My bot shows offline.)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.
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.