Merge pull request #1637 from turt2live/travis/c2s/clarify-errors

List known client-server error codes; Clarify priority of error codes vs http status code
pull/977/head
Travis Ralston 6 years ago committed by GitHub
commit bb2835651f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -0,0 +1 @@
Clarify the available error codes, and when to prefer the HTTP status code over the ``errcode``.

@ -102,7 +102,16 @@ custom namespace ``com.mydomain.here``, and a
``COM.MYDOMAIN.HERE_FORBIDDEN``. There may be additional keys depending on the
error, but the keys ``error`` and ``errcode`` MUST always be present.
Some standard error codes are below:
Errors are generally best expressed by their error code rather than the HTTP
status code returned. When encountering the error code ``M_UNKNOWN``, clients
should prefer the HTTP status code as a more reliable reference for what the
issue was. For example, if the client receives an error code of ``M_NOT_FOUND``
but the request gave a 400 Bad Request status code, the client should treat
the error as if the resource was not found. However, if the client were to
receive an error code of ``M_UNKNOWN`` with a 400 Bad Request, the client
should assume that the request being made was invalid.
The common error codes are:
:``M_FORBIDDEN``:
Forbidden access, e.g. joining a room without permission, failed login.
@ -110,6 +119,9 @@ Some standard error codes are below:
:``M_UNKNOWN_TOKEN``:
The access token specified was not recognised.
:``M_MISSING_TOKEN``:
No access token was specified for the request.
:``M_BAD_JSON``:
Request contained valid JSON, but it was malformed in some way, e.g. missing
required keys, invalid values for keys.
@ -124,7 +136,16 @@ Some standard error codes are below:
Too many requests have been sent in a short period of time. Wait a while then
try again.
Some requests have unique error codes:
:``M_UNKNOWN``:
An unknown error has occurred.
Other error codes the client might encounter are:
:``M_UNRECOGNIZED``:
The server did not understand the request.
:``M_UNAUTHORIZED``:
The request was not correctly authorized. Usually due to login failures.
:``M_USER_IN_USE``:
Encountered when trying to register a user ID which has been taken.
@ -144,6 +165,13 @@ Some requests have unique error codes:
:``M_THREEPID_NOT_FOUND``:
Sent when a threepid given to an API cannot be used because no record matching the threepid was found.
:``M_THREEPID_AUTH_FAILED``:
Authentication could not be performed on the third party identifier.
:``M_THREEPID_DENIED``:
The server does not permit this third party identifier. This may happen if the server only
permits, for example, email addresses from a particular domain.
:``M_SERVER_NOT_TRUSTED``:
The client's request used a third party server, eg. identity server, that this server does not trust.
@ -154,6 +182,38 @@ Some requests have unique error codes:
The client attempted to join a room that has a version the server does not support. Inspect the
``room_version`` property of the error response for the room's version.
:``M_BAD_STATE``:
The state change requested cannot be performed, such as attempting to unban
a user who is not banned.
:``M_GUEST_ACCESS_FORBIDDEN``:
The room or resource does not permit guests to access it.
:``M_CAPTCHA_NEEDED``:
A Captcha is required to complete the request.
:``M_CAPTCHA_INVALID``:
The Captcha provided did not match what was expected.
:``M_MISSING_PARAM``:
A required parameter was missing from the request.
:``M_INVALID_PARAM``:
A parameter that was specified has the wrong value. For example, the server
expected an integer and instead received a string.
:``M_TOO_LARGE``:
The request or entity was too large.
:``M_EXCLUSIVE``:
The resource being requested is reserved by an application service, or the
application service making the request has not created the resource.
.. TODO: More error codes (covered by other issues)
.. * M_CONSENT_NOT_GIVEN - GDPR: https://github.com/matrix-org/matrix-doc/issues/1512
.. * M_CANNOT_LEAVE_SERVER_NOTICE_ROOM - GDPR: https://github.com/matrix-org/matrix-doc/issues/1254
.. * M_RESOURCE_LIMIT_EXCEEDED - Limits: https://github.com/matrix-org/matrix-doc/issues/1504
.. _sect:txn_ids:
The client-server API typically uses ``HTTP PUT`` to submit requests with a

Loading…
Cancel
Save