Discord error 4008: Rate limited

You exceeded the gateway send limit: 120 events per connection per 60 seconds (roughly 2 per second), across all opcodes including heartbeats. Unlike REST rate limits, the gateway does not return a 429 and wait; it closes the socket with 4008 and you must reconnect. Discord marks it reconnectable, and a Resume usually succeeds, but the events you were sending in the burst are gone.

The usual offenders are presence updates and Request Guild Members. A bot that changes its status on every message, or that requests members for many guilds in a loop at startup (for example to build a cache without the Server Members intent), will hit 120 quickly. Voice State Updates in a music bot that joins and leaves rapidly can also contribute. Heartbeats are sent by the library at the interval Discord specifies and count toward the total, but on their own they are nowhere near the limit.

The budget is small and shared by everything the connection sends: Identify, Resume, heartbeats (one every ~41 seconds, so a negligible slice), presence updates, voice state updates and member requests all draw from the same 120. Unlike a REST 429, there is no retry_after and no chance to slow down mid-window; the first payload over the line closes the socket and any sends you had queued are simply lost. The resume that follows replays missed inbound events, but your outbound burst is gone. The compounding failure is the reconnect itself: each fresh Identify consumes one of the ~1,000 daily session starts, so a bot that hits 4008 in a tight loop eventually cannot connect at all until the daily window resets, which looks like a completely unrelated outage.

// WebSocket close frame
code: 4008
reason: "Rate limited."

Put every outbound gateway send behind a single queue with a 120-per-60s budget and a small reserve for heartbeats. Audit presence-update call sites; they are almost always the culprit when 4008 appears.

The 120-per-60s figure and the session start budget it interacts with are on the Discord limits page; for pacing strategy that applies across platforms, see chatbot API rate limiting.