matrix-org / matrix-org/matrix-spec
Are HTTP status codes in the spec normative? Exhaustive?
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
**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:
- https://github.com/matrix-org/synapse/issues/13102#issuecomment-1163541302
> 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.
- #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.
- #1034
- #1105
Contributor guide
Research direction
Start by reviewing the API pages and the related discussions in issues #464, #1034, and #1105. Done means resolving whether listed HTTP status codes are normative and exhaustive, and documenting the resulting guidance and any required specification-change process.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100