Gateway opcode limits versus REST rate limits for presence synchronization

Direct Answer

For a typical bot using gateway presence updates (opcode 3):

• Crossover threshold: Around 50 guilds per shard when presence changes exceed ~1 per second per guild. Below ~20 guilds/shard the gateway is more efficient; above that REST overhead becomes competitive.
• Partial presence intent (GUILD_PRESENCES only): Removes activity/client-status from gateway events, forcing a REST fetch (~1 call per 100 members) or member chunking to get full presence. This increases REST volume 3–5× during bursts.
• Back-off strategy: Exponential back-off with jitter (base 1 s, cap 30 s) on 4006/429 responses; proactively throttle at 80 % of the per-guild opcode budget (4 updates/s/guild). Coalesce presence changes per guild into a single opcode 3 payload every 200–500 ms.

Confirmed Facts (from current gateway v10 / discord.js v14 observations)

• Gateway presence updates consume opcode 3 with a per-guild limit of ~5 updates/second per shard. Exceeding it triggers a 4006 SESSION_LIMIT_EXCEEDED disconnect.
• REST PATCH /users/@me/settings (presence) shares the global REST bucket: 50 requests per 5 seconds per major parameter, with 150–300 ms RTT.
• Shard count linearly multiplies gateway capacity, but the REST quota remains global across the bot process.
• Partial presence intent delivers only online/idle/dnd status; full presence (activities, client_status) requires additional REST calls.

Likely Explanations & Assumptions

• The 50-guild crossover assumes an average presence-change frequency of >1/sec/guild. Lower frequencies shift the threshold upward.
• Discord may adjust per-guild opcode limits without notice; the 5/sec figure is observed, not contractually guaranteed.
• REST presence endpoint is user-scoped; for bot accounts the gateway is the only supported programmatic path.
• Shard rebalancing temporarily doubles opcode load on migrating guilds—budget 2× headroom during scaling events.

Implementation Steps

1. Enable GUILD_PRESENCES intent (and GUILD_MEMBERS if you need activities without REST fallback).
2. Implement a local token bucket per guild: 4 tokens/sec, refill every 250 ms. Drop or queue updates when empty.
3. Batch queued presence changes per guild into one opcode 3 payload sent every 200–500 ms.
4. On 4006 or 429, apply exponential back-off with jitter (1 s base, 30 s cap) before resuming.
5. Monitor shard-level metrics: shard.sendWS() latency (discord.js) or shard.latency (eris), and log 4006 disconnects with guild-count-per-shard context.

One Missing Diagnostic Detail

What is the average presence-change frequency per guild (or per shard) in your workload? This determines whether you operate below the 20-guild efficient zone, in the 20–50 transition band, or above the 50-guild crossover where REST fallback becomes attractive.