matrix-org / matrix-org/matrix-spec

Please clarify the relation between HTTP error codes and failure state of the payload

Open
#907 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

clarification
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.