Are HTTP status codes in the spec normative? Exhaustive?

[DMRobertson]

Link to problem area: every API page

Issue

The spec typically specifies that an endpoint returns 200 with a success payload, or 4xx with an error payload. In many cases the status codes listed for HTTP errors are few, and there may be more appropriate ones to choose from. Additionally, I think endpoints almost never specify which matrix error code (e.g. M_UNKNOWN) to return.

It's straightforward enough to change the text of the spec to allow new status codes, but it's not clear if doing so is a backward incompatible change that requires MSCs etc.

Related:

• Documentation incorrectly states that the room list always returns an empty list if disabled, while federation actually returns a 403 error synapse#13102 (comment)

  it is never clear to me if a list of status codes in the spec is normative and/or exhaustive. I think in practice not, because servers can fall over and return 500 at any time.

• Wrong status code for 'invalid request payload' errors? #464, which concisely summarises this

  However, with the current ambiguity in the specification on whether the HTTP status codes are normative or non-normative, there's a good chance that some clients are relying on these sort of errors having a 400 status code either way, M_UNKNOWN or not. Which means that this seems like it would need a specification change to resolve, unless there's some sort of existing guidance on this that I'm not aware of.

• Consider prohibiting or avoiding responses with a 502 Bad Gateway and 504 Gateway Timeout HTTP status code #1034
• Spec does not describe the behaviour of /event/<event ID> when that event is not available #1105

[richvdh]

also related:

• Provide a full reference of all the different error codes (SPEC-309) #140
• Include error codes in schema for errors #361
• Consider making error codes spec-independent (put them in the appendix) #363

[Johennes]

For reference, the gematik spec (which builds upon the Matrix spec) treats HTTP status codes as normative and currently assumes them to be normative in the Matrix spec, too. I think they should not be exhaustive though because an implementation should be allowed to define custom status codes for cases not covered by the spec.