Buckets
Each route has a bucket, counted separately per major resource (channel, server, webhook or interaction) and per caller. Every v1 response carries:
X-RateLimit-Limit: requests allowed in the window.X-RateLimit-Remaining: how many are left.X-RateLimit-Reset: when it resets (epoch seconds, with decimals).X-RateLimit-Reset-After: seconds until it resets.X-RateLimit-Bucket: bucket id (different routes may share one).
429
HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793700123.512
X-RateLimit-Reset-After: 1.512
X-RateLimit-Bucket: 9f2c1a7b3e4d5c6f
X-RateLimit-Scope: shared
{ "code": "RATE_LIMITED", "message": "You are being rate limited", "status": 429, "retryAfter": 1.512, "retry_after": 1.512, "global": false }Wait retryAfter seconds (or the Retry-After header) before retrying. X-RateLimit-Scope says whether the limit is yours (user), global (global) or the resource’s (shared). There is also a global limit of 50 requests per second per bot (interaction responses are exempt). Addresses that pile up many 401/403 responses are blocked for 10 minutes.
Errors
UNAUTHORIZED(401): missing, invalid or rotated token.MISSING_SCOPE/BOT_ONLY(403): the OAuth2 token lacks the scope, or the route is bots only.MISSING_PERMISSIONS(403): a server or channel permission is missing.MISSING_INTENT(403): enable the privileged intent in the portal.NOT_FOUND(404): doesn’t exist or the bot can’t see it.VALIDATION(400): invalid body or parameters (detailexplains).INTERACTION_ALREADY_ACKNOWLEDGED(400): already answered or past the 3 seconds.RATE_LIMITED(429) andINTERNAL(500).