Discord error 429: HTTP 429 Too Many Requests (rate limited)

You sent more requests than a rate limit bucket allows, and Discord refused this one. Discord rate limits at several levels at once. Every bot has a global limit of 50 requests per second across all routes. Below that, each route (or group of routes) has its own per-route bucket with a limit and a reset window, identified by the X-RateLimit-Bucket header; buckets are usually scoped by major parameter (channel ID, guild ID, webhook ID), so sending in one channel does not consume another channel's budget. Some limits are shared across all bots for a resource (scope shared), such as per-channel write limits, and some are emoji- or guild-specific.

The 429 body tells you what to do: retry_after is the number of seconds (float) to wait; global is true when you hit the 50/s global limit (in which case every request must pause, not just this route); and an optional code appears when a resource-specific limit like slowmode (20016) caused it. The Retry-After header carries the same value in whole seconds, and X-RateLimit-Scope says user, global or shared.

Every successful response also includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (epoch seconds) and X-RateLimit-Reset-After. A well-behaved client tracks these and stops before Remaining hits 0, so 429s are rare. Note that 429s (along with 401 and 403) count as invalid requests; 10,000 of them in 10 minutes triggers a temporary Cloudflare ban of your IP. Interaction response endpoints are exempt from the global limit.

Reading the headers in order turns a mystery 429 into a diagnosis. X-RateLimit-Limit: 10 says the bucket allows ten requests per window. X-RateLimit-Remaining: 0 says you spent them all. X-RateLimit-Reset-After: 64.57 says the window reopens in 64.57 seconds. X-RateLimit-Bucket: abcd1234 is the stable hash of the underlying bucket: two different routes returning the same hash share one budget, revealing which routes pool their budget. X-RateLimit-Scope closes the loop: user means your bot spent the budget, shared means every bot writing to that resource shares it, and global means you crossed the 50/s ceiling. Retrying immediately is the expensive mistake: 429s count toward the 10,000-invalid-requests-per-10-minutes ceiling, and crossing it gets the IP temporarily banned by Cloudflare in front of the API, where every request returns Cloudflare's HTML "error 1015" page instead of JSON until the ban lapses.

HTTP/1.1 429 TOO MANY REQUESTS
Content-Type: application/json
Retry-After: 65
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1470173023.123
X-RateLimit-Reset-After: 64.57
X-RateLimit-Bucket: abcd1234
X-RateLimit-Scope: user

{
  "message": "You are being rate limited.",
  "retry_after": 64.57,
  "global": false
}

// global variant
X-RateLimit-Global: true
X-RateLimit-Scope: global
{
  "message": "You are being rate limited.",
  "retry_after": 1.2,
  "global": true
}

Design for the limits instead of reacting to them: one outbound queue per bucket, a global 50/s ceiling, and proactive waiting on X-RateLimit-Remaining: 0. Keep the full table of limits in view (Discord limits) and treat any 429 in logs as a bug to investigate. For the broader pattern across platforms see chatbot API rate limiting.

Every rate limit in one table, including the headers and the invalid-request ceiling, is at Discord limits: REST rate limits.