Rate-limiting behaviour is not well-defined for clients in the Client-Server API

[reivilibre]

Link to problem area: https://spec.matrix.org/v1.11/client-server-api/#rate-limiting

• The spec doesn't say that the server must (or even should!) use a 429 status code — it only hints it by mentioning it in passing
• The spec doesn't say what a client is meant to do if it receives a 429 status code, but no JSON body, or a JSON body with a different error type, or without a retry-after.
  • In fact, the spec doesn't really say what a client is meant to do — full stop. It is only hinted at by what servers 'should' do. Overall it is very loose.

Example real-world case where this matters is that matrix.org's Synapse converts 503s to 429s to avoid cloudflare taking the whole system down. These 429s don't have a retry-after time and they have an M_UNKNOWN error code.

Is this dodgy? Should clients be ready to handle this? The spec only makes some suggestions with SHOULD but doesn't clarify for servers or clients what is allowed and what isn't.

It is worth remembering that middleboxes, not understanding Matrix, may have reason to inject 429 response codes.