From e6adf9f6b971ad5677d89359a402568c5ccf387e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 23:05:51 -0600 Subject: [PATCH] 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