PUBLISHED PROVIDER LIMITS
Limits keep their provider-specific dimensions.
Discord explicitly advises clients not to hard-code most limits. Parse response headers and 429 bodies.
Authentication: Bot token, OAuth access token, Webhook token, Unauthenticated request where supported
Primary scope: Bot, User, IP, Route Bucket, Or Top Level Resource
Measured dimensions: Requests, Route Buckets, Invalid Requests
Profile coverage: Discord HTTP API dynamic route buckets, the bot global limit, invalid-request enforcement, rate-limit headers, and 429 response behavior. Gateway connection and event limits are outside this profile.
Route limits
| Limit | Value | Period | Scope | Conditions and variability |
|---|---|---|---|---|
| Per-route HTTP API limits | Provider-specific | Provider-defined | Route Bucket And Major Resource | Depends on route, method, and major resource. Discover from X-RateLimit headers. |
Global limits
| Limit | Value | Period | Scope | Conditions and variability |
|---|---|---|---|---|
| Global HTTP API limit | 50 requests | Per second | Bot Or User | Authenticated bot or user requests |
Invalid-request enforcement
| Limit | Value | Period | Scope | Conditions and variability |
|---|---|---|---|---|
| Invalid request limit | 10,000 invalid requests | Per 10 minute | Source Ip | Primarily 401, 403, and 429 responses Exceeding this threshold can trigger a temporary Cloudflare ban. |
RESPONSE METADATA
Headers expose the applicable limit state.
X-RateLimit-LimitFormat: Integer- Requests permitted in the current bucket.
X-RateLimit-RemainingFormat: Integer- Requests remaining in the current bucket.
X-RateLimit-ResetFormat: Unix Epoch Seconds- Epoch time when the bucket resets.
X-RateLimit-Reset-AfterFormat: Decimal Seconds- Seconds until the current bucket resets; decimals can be present.
X-RateLimit-BucketFormat: String- Opaque identifier for a shared route-limit bucket.
X-RateLimit-GlobalFormat: Boolean- On a 429, indicates that the global limit was hit.
X-RateLimit-ScopeFormat: Enum- Scope of the 429 limit.Known values: user, global, shared
Retry-AfterFormat: Decimal Seconds- Seconds to wait before retrying.
WHEN A LIMIT IS EXCEEDED
Read the response before choosing a delay.
- Rate-limit responses can use HTTP 429.
- Message: Human-readable rate-limit message.
- Retry After: Seconds to wait before another request.
- Global: Whether the global limit was hit.
- Code: Optional Discord error code.
RECOMMENDED HANDLING
Protect both the provider and your own queue.
- Parse rate-limit headers instead of hard-coding per-route limits.
- Group routes using X-RateLimit-Bucket plus the relevant major resource.
- Honor Retry-After or the retry_after response field.
- Avoid repeated invalid requests that can trigger Cloudflare enforcement.
VERIFICATION RECORD