Add error codes from MSC4178 (#1944)

* Add error codes from MSC4178

* changelog

* Put changelog in the right place

* Move newsfile

* Add the codes to the right endpoint

* Also add M_THREEPID_IN_USE

which was always used and is specified in the IS API, but not in the
C/S API. We decided this was well-specced enough that it didn't need
its own MSC.

changelogs/client_server/newsfragments/1944.feature

@@ -0,0 +1 @@
+Add error codes to requestToken endpoints (MSC4178).

content/client-server-api/_index.md

@@ -222,6 +222,13 @@ only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
 The user is unable to reject an invite to join the server notices room.
 See the [Server Notices](#server-notices) module for more information.
 
+`M_THREEPID_MEDIUM_NOT_SUPPORTED`
+The homeserver does not support adding a third party identifier of the given medium.
+
+`M_THREEPID_IN_USE`
+The third party identifier specified by the client is not acceptable because it is
+already in use in some way.
+
 #### Rate limiting
 
 Homeservers SHOULD implement rate limiting to reduce the risk of being

data/api/client-server/administrative_contact.yaml

@@ -488,9 +488,13 @@ paths:
         "400":
           description: |-
             The third-party identifier is already in use on the homeserver, or
-            the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
-            can be returned if the server does not trust/support the identity server
-            provided in the request.
+            the request was invalid. Error codes that can be returned are:
+              * `M_THREEPID_IN_USE`: The email supplied cannot be bound because is is already
+                associated with a different Matrix ID.
+              * `M_SERVER_NOT_TRUSTED`: The server does not trust/support the identity server
+                provided in the request.
+              * `M_THREEPID_MEDIUM_NOT_SUPPORTED`: The homeserver does not support adding email addresses.
+              * `M_INVALID_PARAM`: The email address given was not valid.
           content:
             application/json:
               schema:
@@ -547,9 +551,12 @@ paths:
         "400":
           description: |-
             The third-party identifier is already in use on the homeserver, or
-            the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
-            can be returned if the server does not trust/support the identity server
-            provided in the request.
+            the request was invalid. Error codes that can be returned are:
+              * `M_THREEPID_IN_USE`: The phone number supplied cannot be bound because is is already
+                associated with a different Matrix ID.
+              * `M_SERVER_NOT_TRUSTED`: The server does not trust/support the identity server
+              * `M_THREEPID_MEDIUM_NOT_SUPPORTED`: The homeserver does not support adding phone numbers.
+              * `M_INVALID_PARAM`: The phone number given was not valid.
           content:
             application/json:
               schema: