Clarify per-user rate limit override documentation

[aouxwoux]

Clarifies that non-zero per-user overrides apply to message sending, names the override consistently across the API operations, and explains that deleting it restores the configured default.

Fixes #18885.

[CLAassistant]

All committers have signed the CLA.

[anoadragon453]

Unfortunately this is a bit more confusing than just "messages per second". There are two ratelimiter classes which make use of the database rows this Admin API modifies:

• RequestRatelimiter uses non-zero messages_per_second / burst_count as a per-user override for normal event sending. messages_per_second = 0 disables that limiter entirely for the user.
• Ratelimiter only treats a zero/null messages_per_second as “disable this limiter for this requester”. Non-zero values are not applied to these limiters.

Asking an LLM what individual endpoints this would affect:

Affected Endpoints

Non-zero overrides affect normal event-send rate limiting, and zero disables it:

• Room events: POST /rooms/{room_id}/send/{event_type}, PUT /rooms/{room_id}/send/{event_type}/{txn_id}
• State events: PUT /rooms/{room_id}/state/{event_type} and PUT /rooms/{room_id}/state/{event_type}/{state_key}
• Redactions: POST /rooms/{room_id}/redact/{event_id}, PUT /rooms/{room_id}/redact/{event_id}/{txn_id}
• Membership events: /join/{room_identifier}, /rooms/{room_id}/{join|invite|leave|ban|unban|kick}, PUT /rooms/{room_id}/state/m.room.member/{user_id}, and POST /knock/{room_identifier}
• Room creation and upgrade operation limits: /createRoom, /rooms/{room_id}/upgrade
• Delayed event scheduling via org.matrix.msc4140.delay, and eventual delayed event sending
• Profile display name/avatar updates when they propagate membership updates
• POST /_synapse/admin/v1/rooms/{room_identifier}/make_room_admin, for the local room-admin user Synapse chooses to send the PL/invite events as

Zero/null messages_per_second additionally disables these requester-aware plain Ratelimiter checks:

• POST /_matrix/media/v1/create
• Presence updates: PUT /presence/{user_id}/status, and /sync’s set_presence update path
• POST /user_directory/search
• Room hierarchy: GET /rooms/{room_id}/hierarchy, GET /_synapse/admin/v1/rooms/{room_id}/hierarchy
• Delayed event management: GET /org.matrix.msc4140/delayed_events, POST /org.matrix.msc4140/delayed_events/{delay_id}, and /cancel|/restart|/send variants
• POST /users/{target_user_id}/report
• Cross-user room-key requests via PUT /sendToDevice/m.room_key_request/{txn_id}
• Extra invite/join-specific limits: invite per room, invite per recipient, invite per issuer, local/remote joins, joins per room, 3PID invite limits
• Failed UIA attempt throttling for endpoints using validate_user_via_ui_auth: logged-in POST /account/password, POST /account/deactivate, POST /account/3pid/add, POST /delete_devices, DELETE /devices/{device_id}, POST /keys/device_signing/upload, and POST /
  login/get_token when UIA is required

Not Affected

These use requester=None, IP keys, room keys, destination keys, or separate rate-limit utilities:

• /login address/account/failed-login limiters
• Registration limiters: /register, /register/available, registration-token validity
• 3PID validation request-token limiters
• Remote media download byte limiter
• Federation request rate limits and federation make/send join room limits
• /login/get_token’s own 1-per-minute token issuance limiter
• Event report and room report endpoints; only user report is affected
• Room summary endpoint; room hierarchy is affected
• Custom profile fields; only display name/avatar propagation is affected

---

So I think we can reliably say that setting message_per_second should disable ratelimits which act based on user ID, rather than any other key. But setting it to something higher than 0 will only affect "sending events and creating/upgrading rooms".