2.2 KiB
MSC4041: Use http header Retry-After to enable library-assisted retry handling
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 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, got
and urllib3) ease
the burden of handling retries by honoring the http header Retry-After. As explained in
RFC 9119 - HTTP Semantics 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
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.
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 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:
Retry-Afterhttp header.retry_after_msproperty 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