Document known client-server error codes
Covers part of (updating all the endpoints is being done as a separate PR/commit).
Reference:
@@ -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
