From e6adf9f6b971ad5677d89359a402568c5ccf387e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 23:05:51 -0600 Subject: [PATCH 1/3] Document known client-server error codes Covers part of https://github.com/matrix-org/matrix-doc/issues/603 (updating all the endpoints is being done as a separate PR/commit). Reference: https://github.com/matrix-org/synapse/blob/74854a97191191b08101821753c2672efc2a65fd/synapse/api/errors.py#L30-L61 --- specification/client_server_api.rst | 55 ++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index b377cbb8..cac83cfd 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -102,12 +102,17 @@ error, but the keys ``error`` and ``errcode`` MUST always be present. Some standard error codes are below: +The common error codes are: + :``M_FORBIDDEN``: Forbidden access, e.g. joining a room without permission, failed login. :``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. @@ -122,7 +127,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. @@ -145,6 +159,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. ID server, that this server does not trust. @@ -155,6 +176,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 From d57b40d0cc1f4ae6f949f58da1850375784bc368 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 23:06:32 -0600 Subject: [PATCH 2/3] Clarify how the client should treat errors This is based on observation and rough interpretation and may need additional review from people. Fixes https://github.com/matrix-org/matrix-doc/issues/1188 --- specification/client_server_api.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index cac83cfd..489b8e0b 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -100,7 +100,14 @@ 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: From ac56e7674682f27e609860c3152b14a15d7ccb77 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 23:09:37 -0600 Subject: [PATCH 3/3] Changelog --- changelogs/client_server/newsfragments/1637.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1637.clarification diff --git a/changelogs/client_server/newsfragments/1637.clarification b/changelogs/client_server/newsfragments/1637.clarification new file mode 100644 index 00000000..5833554d --- /dev/null +++ b/changelogs/client_server/newsfragments/1637.clarification @@ -0,0 +1 @@ +Clarify the available error codes, and when to prefer the HTTP status code over the ``errcode``.