matrix-org / matrix-org/matrix-spec
Please clarify the relation between HTTP error codes and failure state of the payload
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
**Link to problem area**: https://spec.matrix.org/unstable/client-server-api/#standard-error-response
**Issue**
The section about error codes currently only specifies that errors need to be signaled through a standard error response in form of a JSON object and that the error code in the JSON payload should have precedence over that in the HTTP error code. But for me it leaves these questions unanswered:
* Does the return of a HTTP error code (>400 && <= 599) imply that no successful JSON response is returned, i.e. a standard error response is returned or the server so broken that it returns something entirely else (e.g. a HTML error page from NGINX)?
* Does the return of a successful HTTP code (>200 && <=299) imply that a successful JSON response is returned, i.e. no standard error response is returned?
Intuitively I would think that the answer to both questions should be yes, but I don't see any place in the spec where it explicitly says so. If the answer to these questions is yes, it should probably be explicitly mentioned in the spec. If the answer is no, it should probably be explicitly mentioned as well, so people like me don't end up making invalid assumptions about the relation between HTTP return codes and the response payload.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Matrix Client-Server API's “Standard error response” section linked in the issue, and review how it describes HTTP status codes and the JSON error code. Clarify in the specification whether HTTP success or error status implies a corresponding successful or standard error JSON response, or explicitly document that no such implication exists.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100