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

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``.

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