diff --git a/proposals/4041-retry-after-header-rate-limiting.md b/proposals/4041-retry-after-header-rate-limiting.md new file mode 100644 index 00000000..9e61e320 --- /dev/null +++ b/proposals/4041-retry-after-header-rate-limiting.md @@ -0,0 +1,50 @@ +# 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 +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 +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 +[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 +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 +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 +`retry_after_ms` property in the response body. + +Client libraries shall use the values in this order: + +1) `Retry-After` http header. +2) `retry_after_ms` property in the response body. + +## Alternatives + +N/A + +## Security considerations + +N/A + +## Unstable prefix + +Since this MSC is using a standard HTTP header, it will not use a unstable prefix. + +## Dependencies + +N/A \ No newline at end of file