
Most Discord bot rate limit errors come from the bot itself: too many requests to one route, a burst of invalid requests, or a slash command that takes longer than 3 seconds to answer. Discord documents every one of these limits, so the fix starts with finding out which one you hit.
This guide explains the two connections your bot uses, how to read a 429, the invalid request limit that can lock out a whole IP address, and the code changes that stop the errors.
The two connections every bot uses
1. The Gateway (WebSocket)
The Gateway is a WebSocket connection, wss://gateway.discord.gg, that streams events to your bot in real time: messages, reactions, members joining. The rules that matter for timeouts, from Discord's gateway docs:
- Your bot sends a heartbeat at the interval Discord gives it in the Hello event (45,000 ms in the docs' example).
- If a heartbeat is not acknowledged, the connection counts as failed or "zombied": close it, reconnect and resume.
- A bot can send 120 gateway events per connection every 60 seconds. Going over disconnects the bot immediately, and repeat offenders lose API access.
- Identifying is limited too:
max_concurrencysets how many identify requests are allowed per 5 seconds, and a bot gets 1,000 IDENTIFY calls per 24 hours across all shards. Resumes do not count.
A bot that reconnects in a tight loop after every crash burns through those identify calls. That is why a restart policy with a short delay beats an instant restart loop.
2. The REST API (HTTP)
When your bot acts, for example replying to a command, editing roles, sending messages or banning a user, it sends an HTTP request to Discord's API. The limits, from Discord's rate limit docs:
- Global limit: a bot can make up to 50 requests per second. Interaction endpoints are not bound to it.
- Per-route limits: individual endpoints have their own buckets, sometimes per HTTP method, and some buckets are shared between similar endpoints. A route's limit is counted separately for each channel, guild or webhook in its path.
Reading a 429
When you hit a limit, Discord answers with HTTP 429 and tells you exactly what happened:
| Header or field | What it tells you |
|---|---|
X-RateLimit-Limit | How many requests the bucket allows |
X-RateLimit-Remaining | How many are left |
X-RateLimit-Reset-After | Seconds until the bucket resets, with decimals |
X-RateLimit-Bucket | Which bucket you hit, so you can see which routes share it |
X-RateLimit-Global | Sent when the global limit was hit, not a route limit |
X-RateLimit-Scope | user (your bot's limit), global (your bot's global limit) or shared (a limit on the resource) |
retry_after in the body | Seconds to wait before the next request |
Discord's docs say to rely on Retry-After or retry_after to decide when to retry. A bot that ignores them and retries straight away is the usual reason a single 429 turns into a lockout.
The invalid request limit
This is the limit that takes bots down completely. Discord temporarily restricts an IP address that makes 10,000 invalid requests in 10 minutes. Invalid means a response with status 401, 403 or 429; a 429 with X-RateLimit-Scope: shared does not count.
The common causes:
- A 401 loop. The token was reset or is wrong, and the bot keeps retrying.
- A 403 loop. The bot lacks a permission, for example to manage a role above its own, and tries again on every event.
- Ignored 429s. Retrying before
retry_afteris up counts as another invalid request.
Because the restriction applies to the IP address, it also matters who else uses yours. On shared hosting, one badly written bot on the same IP can push the address over the limit for everyone on it.
The 3 second interaction deadline
When a user runs a slash command, your bot must send its first response within 3 seconds, or the interaction token is invalidated. After that first response, the token stays valid for 15 minutes for follow-up messages and edits (interaction docs).
So if a command calls a database, an AI model or another API, defer first and answer later:
// Acknowledge right away: the user sees a loading state
await interaction.deferReply();
// Now do the slow work
const result = await queryAIModel(interaction.options.getString('prompt'));
// Edit the deferred reply with the result (within 15 minutes)
await interaction.editReply({ content: result });
deferReply() sends the deferred response type that Discord calls DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE. For buttons and select menus, deferUpdate() acknowledges without a loading state.
Fixes in code
Let the library handle rate limits
Use your library's REST client instead of raw HTTP calls. In discord.js, the REST client queues requests per route, keeps to Discord's global limit of 50 requests per second by default (globalRequestsPerSecond), retries a request up to 3 times after a 500 error or a timeout, and aborts a request after 15 seconds (RESTOptions in the discord.js docs):
const { REST } = require('@discordjs/rest');
const rest = new REST({ version: '10' })
.setToken(process.env.DISCORD_TOKEN);
Log rate limits and invalid requests
discord.js stays quiet about invalid requests unless you ask. Set invalidRequestWarningInterval and it warns every time that many 401, 403 or 429 responses pile up in a 10 minute window:
const { Client, GatewayIntentBits } = require('discord.js');
const client = new Client({
intents: [GatewayIntentBits.Guilds],
rest: { invalidRequestWarningInterval: 500 },
});
client.rest.on('rateLimited', (info) => {
console.warn('Rate limited:', info);
});
client.rest.on('invalidRequestWarning', (info) => {
console.warn('Invalid requests in the last 10 minutes:', info);
});
A warning at 500 leaves plenty of room before Discord's 10,000, so you can fix the loop before the IP is restricted.
Stop retrying what will never work
On a 401, stop the bot and check the token. On a 403, log which permission is missing and skip that action instead of retrying it on every event.
Watch the gateway connection
client.on('shardDisconnect', (event, shardId) => {
console.error(`Shard ${shardId} disconnected:`, event);
});
client.on('shardReconnecting', (shardId) => {
console.log(`Shard ${shardId} reconnecting...`);
});
// Heartbeat round trip in ms
setInterval(() => {
console.log(`WS ping: ${client.ws.ping}ms`);
}, 30000);
client.ws.ping is the heartbeat round trip measured from wherever your bot runs, which is the number to trust over any latency table.
When the host matters
Two things about the host affect rate limits, and neither is about distance:
- The IP address. Since the invalid request limit counts per IP, a shared IP shares the risk. Our Discord bot hosting has two add-ons for busy bots: a Low Traffic IP shared with only a handful of other bots (€6.00 per 6 months) and a Dedicated IP that nobody else uses (€18.00 per 6 months).
- Restarts. A host that restarts a crashed bot automatically, after a short pause, keeps you away from the identify limit and brings the bot back without you watching it.
If 429s keep coming after these fixes, read the bucket header on the failing request: it tells you which route to slow down.