Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MSC4041 - Add Retry-After header notice. #1737

Merged
merged 9 commits into from
Mar 20, 2024
Merged

MSC4041 - Add Retry-After header notice. #1737

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ecae6b2
Add Retry-After header notice.
Half-Shot Mar 4, 2024
dd47804
Remove extra newline.
Half-Shot Mar 4, 2024
aa65bfb
Create 1737.feature
Half-Shot Mar 4, 2024
c04ef8e
Update content and move ratelimit section.
Half-Shot Mar 13, 2024
0e24942
Clean up.
Half-Shot Mar 13, 2024
262027f
changes
Half-Shot Mar 19, 2024
fe1b0d4
be consistent with property
Half-Shot Mar 19, 2024
46dbddb
Update content/client-server-api/_index.md
Half-Shot Mar 20, 2024
8def27a
Update changelogs/client_server/newsfragments/1737.feature
Half-Shot Mar 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/1737.feature
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Specify that the `Retry-After` header may be used to rate-limit a client.
Half-Shot marked this conversation as resolved.
Show resolved Hide resolved
44 changes: 24 additions & 20 deletions content/client-server-api/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ No resource was found for this request.

`M_LIMIT_EXCEEDED`
Too many requests have been sent in a short period of time. Wait a while
then try again.
then try again. See [Rate limiting section](#rate-limiting)
richvdh marked this conversation as resolved.
Show resolved Hide resolved

`M_UNRECOGNIZED`
The server did not understand the request. This is expected to be returned with
Expand Down Expand Up @@ -212,6 +212,29 @@ only read state (e.g.: `/sync`, get account data, etc).
The user is unable to reject an invite to join the server notices room.
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)
}
```

{{% added-in v="1.10" %}}
richvdh marked this conversation as resolved.
Show resolved Hide resolved

The [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after)
HTTP header SHOULD be specified by the server on any 429 code response.
richvdh marked this conversation as resolved.
Show resolved Hide resolved

The `retry_after_ms` key MAY be included to tell the client how long
they have to wait in milliseconds before they can try again. This field is
richvdh marked this conversation as resolved.
Show resolved Hide resolved
deprecated, in favour of the `Retry-After` header.

### Transaction identifiers

The client-server API typically uses `HTTP PUT` to submit requests with
Expand Down Expand Up @@ -2521,25 +2544,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
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 are parts of the Client-Server API which are not universal to
Expand Down
Loading