wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

MSC4041 - Add Retry-After header notice. (#1737)

Browse source
This commit is contained in:
Will Hunt 2024-03-20 09:44:47 +00:00 • committed by GitHub
parent 4247cff2fa
commit e5aa5235fe
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 24 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/1737.feature Normal file
View file

@ -0,0 +1 @@
Specify that the `Retry-After` header may be used to rate-limit a client, as per [MSC4041](https://github.com/matrix-org/matrix-spec-proposals/pull/4041).

43
content/client-server-api/_index.md
View file

@ -106,7 +106,7 @@ No resource was found for this request.
`M_LIMIT_EXCEEDED` `M_LIMIT_EXCEEDED`
Too many requests have been sent in a short period of time. Wait a while Too many requests have been sent in a short period of time. Wait a while
then try again. then try again. See [Rate limiting](#rate-limiting).
`M_UNRECOGNIZED` `M_UNRECOGNIZED`
The server did not understand the request. This is expected to be returned with The server did not understand the request. This is expected to be returned with
@ -212,6 +212,28 @@ only read state (e.g.: `/sync`, get account data, etc).
The user is unable to reject an invite to join the server notices room. The user is unable to reject an invite to join the server notices room.
See the [Server Notices](#server-notices) module for more information. See the [Server Notices](#server-notices) module for more information.
#### Rate limiting
Homeservers SHOULD implement rate limiting to reduce the risk of being
overloaded. If a request is refused due to rate limiting, it should
return a standard error response of the form:
```json
{
"errcode": "M_LIMIT_EXCEEDED",
"error": "string",
"retry_after_ms": integer (optional, deprecated)
}
```
Homeservers SHOULD include a [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after)
for any response with a 429 status code.
The `retry_after_ms` property MAY be included to tell the client how long
they have to wait in milliseconds before they can try again. This property is
deprecated, in favour of the `Retry-After` header.
{{< changed-in v="1.10" >}}: `retry_after_ms` property deprecated in favour of `Retry-After` header.
### Transaction identifiers ### Transaction identifiers
The client-server API typically uses `HTTP PUT` to submit requests with The client-server API typically uses `HTTP PUT` to submit requests with
@ -2536,25 +2558,6 @@ users, they should include the display name and avatar URL fields in
these events so that clients already have these details to hand, and do these events so that clients already have these details to hand, and do
not have to perform extra round trips to query it. not have to perform extra round trips to query it.
## Security
### Rate limiting
Homeservers SHOULD implement rate limiting to reduce the risk of being
overloaded. If a request is refused due to rate limiting, it should
return a standard error response of the form:
```json
{
"errcode": "M_LIMIT_EXCEEDED",
"error": "string",
"retry_after_ms": integer (optional)
}
```
The `retry_after_ms` key SHOULD be included to tell the client how long
they have to wait in milliseconds before they can try again.
## Modules ## Modules
Modules are parts of the Client-Server API which are not universal to Modules are parts of the Client-Server API which are not universal to