Skip to content

Commit 81721ef

Browse files
colinloretzadvaith1
colinloretz
and
advaith1
authored
[gateway] Introducing Rate Limit When Requesting All Guild Members (#7760)
* Add RATE_LIMITED event * Add changelog * precious tables * precious links * (╯°□°)╯︵ ┻━┻ * Update docs/change-log/2025-08-14-introducing-guild-members-rate-limit.md :ratelimit: Co-authored-by: advaith <[email protected]> * Move RL event up in events table. Update description * Add clarification on initial request, not response events * Shorten changelog with duplicate payload --------- Co-authored-by: advaith <[email protected]>
1 parent 7434f1d commit 81721ef

File tree

2 files changed

+91
-0
lines changed

2 files changed

+91
-0
lines changed

‎docs/change-log/2025-08-14-introducing-guild-members-rate-limit.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: "Introducing Rate Limit When Requesting All Guild Members"
3+
date: "2025-08-14"
4+
topics:
5+
- "Gateway"
6+
---
7+
8+
We're introducing a change to the [Request Guild Members](/docs/events/gateway-events#request-guild-members) gateway opcode.
9+
10+
### What's changing?
11+
12+
We are implementing a rate limit on the [Request Guild Members](/docs/events/gateway-events#request-guild-members) opcode[.](https://takeb1nzyto.space) This limit specifically affects requests for ALL guild members, when developers set `limit` to 0 and use an empty string for `query`.
13+
14+
:::info
15+
Note: This rate limit applies only to the initial request when requesting ALL Guild Members, not to the Guild Members Chunk events that are sent in response.
16+
:::
17+
18+
- **Rate Limit:** 1 request per guild per bot every 30 seconds
19+
- **Scope:** The limit applies per guild per session (one bot can request members for different guilds within the 30-second window)
20+
- **Behavior:** Requests that exceed this limit will receive a [`RATE_LIMITED`](/docs/events/gateway-events#rate-limited) event as a response:
21+
22+
```js
23+
{
24+
"op": 0
25+
"t": "RATE_LIMITED",
26+
"d": {
27+
"opcode": 8,
28+
"retry_after": ...,
29+
"meta": {
30+
"guild_id": ...,
31+
"nonce": ...
32+
}
33+
}
34+
}
35+
```
36+
37+
For example, if you are connected to guilds 123 and 456, you can request members from both guilds within a 30-second period. However, you cannot make a second request to guild 123 within that same 30-second window.
38+
39+
40+
### Impact on Applications
41+
42+
A small number of applications are currently exceeding this rate limit. If your app heavily relies on this opcode, we recommend reviewing your current implementation and making necessary adjustments to maintain functionality.
43+
44+
### Timeline
45+
46+
Most apps won’t encounter this rate limit until it is rolled out to all servers on **October 1, 2025**. However, if you are the developer of an app that is requesting all guild members in very large guilds then you may start seeing this **as soon as today**, so we can ensure platform stability.
47+
48+
### What you need to do
49+
50+
If your application uses [Request Guild Members](/docs/events/gateway-events#request-guild-members) to request all members, we recommend:
51+
52+
- Implement caching mechanisms for member data
53+
- Update your cache using the `GUILD_MEMBER_ADD`, `GUILD_MEMBER_UPDATE`, and `GUILD_MEMBER_REMOVE` gateway events
54+
55+
If you hit this limit, you will receive the [`RATE_LIMITED`](/docs/events/gateway-events#rate-limited) event as a response.

‎docs/events/gateway-events.mdx

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,10 @@ Due to our privacy and infrastructural concerns with this feature, there are som
180180
- Requesting a prefix (`query` parameter) will return a maximum of 100 members
181181
- Requesting `user_ids` will continue to be limited to returning 100 members
182182

183+
:::info
184+
We are introducing a new rate limit to the Request Guild Members opcode. See [Introducing Rate Limit When Requesting All Guild Members](/docs/change-log/2025-08-14-introducing-guild-members-rate-limit) for more information and timeline on this new rate limit.
185+
:::
186+
183187
###### Request Guild Members Structure
184188

185189
| Field | Type | Description | Required |
@@ -306,6 +310,7 @@ Receive events are Gateway events encapsulated in an [event payload](/docs/event
306310
| [Ready](/docs/events/gateway-events#ready) | Contains the initial state information |
307311
| [Resumed](/docs/events/gateway-events#resumed) | Response to [Resume](/docs/events/gateway-events#resume) |
308312
| [Reconnect](/docs/events/gateway-events#reconnect) | Server is going away, client should reconnect to gateway and resume |
313+
| [Rate Limited](/docs/events/gateway-events#rate-limited) | Application was rate limited for a gateway opcode |
309314
| [Invalid Session](/docs/events/gateway-events#invalid-session) | Failure response to [Identify](/docs/events/gateway-events#identify) or [Resume](/docs/events/gateway-events#resume) or invalid active session |
310315
| [Application Command Permissions Update](/docs/events/gateway-events#application-command-permissions-update) | Application command permission was updated |
311316
| [Auto Moderation Rule Create](/docs/events/gateway-events#auto-moderation-rule-create) | Auto Moderation rule was created |
@@ -1466,3 +1471,34 @@ Sent when a user removes their vote on a poll. If the poll allows for multiple s
14661471
| message_id | snowflake | ID of the message |
14671472
| guild_id? | snowflake | ID of the guild |
14681473
| answer_id | integer | ID of the answer |
1474+
1475+
### Rate Limits
1476+
1477+
#### Rate Limited
1478+
1479+
Sent when an app encounters a gateway rate limit for an event, such as [Request Guild Members](/docs/events/gateway-events#request-guild-members).
1480+
1481+
:::info
1482+
See changelog for [Introducing Rate Limit When Requesting All Guild Members](/docs/change-log#introducing-rate-limit-when-requesting-all-guild-members) for more information and timeline on this new rate limit.
1483+
:::
1484+
1485+
###### Rate Limited Fields
1486+
1487+
| Field | Type | Description |
1488+
|-------------|---------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
1489+
| opcode | integer | [Gateway opcode](/docs/topics/opcodes-and-status-codes#gateway-gateway-opcodes) of the event that was rate limited |
1490+
| retry_after | float | The number of seconds to wait before submitting another request |
1491+
| meta | [Rate Limit Metadata for Opcode](/docs/events/gateway-events#rate-limited-rate-limit-metadata-for-opcode-structure) | Metadata for the event that was rate limited |
1492+
1493+
###### Rate Limit Metadata for Opcode Structure
1494+
1495+
| Opcode | Type |
1496+
|--------|-----------------------------------------------------------------------------------------------------------------------------------------|
1497+
| 8 | [Request Guild Member Rate Limit Metadata](/docs/events/gateway-events#rate-limited-request-guild-member-rate-limit-metadata-structure) |
1498+
1499+
###### Request Guild Member Rate Limit Metadata Structure
1500+
1501+
| Field | Type | Description |
1502+
|----------|-----------|-------------------------------------------------------------------------------------------------------|
1503+
| guild_id | snowflake | ID of the guild to get members for |
1504+
| nonce? | string | nonce to identify the [Guild Members Chunk](/docs/events/gateway-events#guild-members-chunk) response |

0 commit comments

Comments
 (0)