Reference
Rate limits
The global limit, per-route buckets, the response headers and the 429 body — Discord's shape, so library back-off works unchanged.
Rate limiting has Discord's shape, and discord.js / discord.py pace themselves off the headers without changes. Two layers apply to every REST request.
Global limit
50 requests per second, fleet-wide across all bots — one shared window, not one per bot. Exceeding it returns 429 with the body {"global": true} and the headers X-RateLimit-Global: true and X-RateLimit-Scope: global. This is a platform-protection ceiling, and its scope is stated here as it is today.
Per-route buckets
Inside the global window, every request falls into a bucket = route template + method. The window is kept per bot and per major parameter — the first path parameter: channel_id, guild_id or webhook_id. Two bots posting into the same channel have separate windows; one bot posting into two channels has separate windows.
The buckets with their own limits; every other route uses the default row:
| Route | Limit | Window |
|---|---|---|
POST /channels/{id}/messages | 5 | 5 s |
PUT / DELETE /channels/{id}/messages/{id}/reactions/{emoji}/@me | 1 | 250 ms |
POST /channels/{id}/typing | 5 | 5 s |
DELETE /channels/{id}/messages/{id} | 5 | 1 s |
PATCH /guilds/{id}/members/{id} | 10 | 10 s |
PATCH /channels/{id} | 2 | 10 min |
POST /webhooks/{id}/{token} | 5 | 2 s |
| everything else | 10 | 10 s |
{id} stands for the major parameter. Requests without a bot token and without a major parameter (/ws, an unauthenticated GET /gateway, the 501 fallback) are not bucketed.
Response headers
Every response carries:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | requests allowed in the bucket's window |
X-RateLimit-Remaining | requests left in the current window |
X-RateLimit-Reset | unix time in seconds when the window resets |
X-RateLimit-Reset-After | seconds until reset, three decimals (4.250) |
X-RateLimit-Bucket | bucket id — the first 16 bytes of SHA-256 over "METHOD /api/v10/route/{template}", hex |
The 429
A bucket 429 adds Retry-After (whole seconds, rounded up) and X-RateLimit-Scope: user, with the body
{ "message": "You are being rate limited.", "retry_after": 2.75, "global": false }retry_after is in seconds (decimal); Retry-After is the same value rounded up to whole seconds. Back off for that long and retry; do not retry in a tight loop — the retry counts against the global window too.
Gateway
The gateway has no request rate limit beyond the heartbeat contract on Gateway. IDENTIFY is not throttled per day the way Discord's session_start_limit describes; the values GET /gateway/bot returns in session_start_limit are informational.