diff --git a/changelogs/client_server/newsfragments/1637.clarification b/changelogs/client_server/newsfragments/1637.clarification new file mode 100644 index 000000000..5833554da --- /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``. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 3fb15105b..dd7a3e19c 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -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