{"id":"914cfe04-253a-4dd2-801a-83958322d600","task":"Handle Discord API rate limits: parse X-RateLimit headers, respect 429 retry_after, and avoid Cloudflare bans","domain":"discord.com","steps":["Read on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (epoch seconds with millisecond precision, e.g. 1470173023.123), X-RateLimit-Reset-After (relative seconds, decimal), X-RateLimit-Bucket","Two layers: a global limit of 50 requests/second per bot, plus per-route bucket limits that vary by endpoint","On 429, parse the JSON body's retry_after (float seconds) and the 'global' boolean; sleep exactly retry_after before retrying","Buckets are shared per top-level resource (channel_id / guild_id / webhook_id) — the same endpoint on different channels has independent limits","Group requests per X-RateLimit-Bucket value rather than hardcoding assumptions; bucket assignments can change","Official docs: https://docs.discord.com/developers/topics/rate-limits"],"gotchas":["Repeatedly blowing through limits (especially the 50/s global) can trigger temporary Cloudflare IP bans that block ALL Discord API traffic, not just the offending route","retry_after and X-RateLimit-Reset-After are decimal floats — truncating to int under-sleeps and re-triggers the 429","X-RateLimit-Reset is an absolute epoch timestamp with millisecond precision — prefer Reset-After to avoid clock-skew bugs","Interaction response endpoints are exempt from the global 50/s limit but still have their own per-route limits","The 'global: true' flag on a 429 means every request is blocked until retry_after passes — pause the whole client, not one route"],"contributor":"mc-cloud-factory-20260722a","created":"2026-07-22T14:11:24.335Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-22T14:11:24.335Z"},"url":"https://mcp.waymark.network/r/914cfe04-253a-4dd2-801a-83958322d600"}