diff --git a/proposals/4041-retry-after-header-rate-limiting.md b/proposals/4041-retry-after-header-rate-limiting.md index 9e61e320..e2f2ed50 100644 --- a/proposals/4041-retry-after-header-rate-limiting.md +++ b/proposals/4041-retry-after-header-rate-limiting.md @@ -1,31 +1,31 @@ # MSC4041: Use http header Retry-After to enable library-assisted retry handling -The current Matrix Client-Server API (v1.7) recommends that home servers should protect themselves from +The current Matrix Client-Server API (v1.7) recommends that homeservers should protect themselves from being overloaded by enforcing rate-limits to selected API calls. -If home servers limit access to an API they respond with an http error code 429 and a response body +If homeservers limit access to an API they respond with an http error code 429 and a response body that includes a property `retry_after_ms` to indicate how long a client has to wait before retrying. Some http libraries (like [Ky](https://github.com/sindresorhus/ky), [got](https://github.com/sindresorhus/got and [urllib3](https://urllib3.readthedocs.io/en/stable/reference/urllib3.util.html#urllib3.util.Retry)) ease -the burden of handling retries by honoring the http header `Retry-After`. As explained in +the burden of handling retries by honoring the http header `Retry-After`. As explained in [RFC 9119 - HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after) this header is optional and contains either a (relative) value for the delay in seconds or an (absolute) date. -The current Matrix Client Server API specification does not take this header into account. This wastes the +The current Matrix Client Server API specification does not take this header into account. This wastes the potential that current http libraries offer in terms of automated retry handling. ## Proposal In order to allow developers to make use of the automated retry handling capabilities of http libraries -home servers shall use the http header `Retry-After` in case they respond with an http error 429. -The value of `Retry-After` (in __seconds__) is meant to be a delay after receiving the response and must be +homeservers shall use the http header `Retry-After` in case they respond with an http error 429. +The value of `Retry-After` (in __seconds__) is meant to be a delay after receiving the response and must be calculated in order to comply with the specification in [RFC 9119 - HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after). With the introduction of the http header `Retry-After` the usage of the existing `retry_after_ms` property in the response body becomes deprecated. ## Potential issues -In order to maintain backward compatibility with existing client libraries home servers shall use both the `Retry-After` header and the +In order to maintain backward compatibility with existing client libraries homeservers shall use both the `Retry-After` header and the `retry_after_ms` property in the response body. Client libraries shall use the values in this order: