Spec Additional Error Codes for submitToken endpoint (#2277)

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/client_server/newsfragments/2277.clarification

@@ -0,0 +1,3 @@
+The optional `submit_url` response parameter of the `/requestToken` endpoints uses the same request
+and response parameters and error codes as the Identity Service API's `POST /_matrix/identity/v2/validate/email/submitToken`,
+as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183).

changelogs/identity_service/newsfragments/2277.clarification

@@ -0,0 +1,3 @@
+Clarify the error codes that can be returned with a 400 HTTP status code by the `POST /_matrix/identity/v2/validate/email/submitToken`
+and `POST /_matrix/identity/v2/validate/msisdn/submitToken` endpoints, introducing the `M_TOKEN_INCORRECT`
+error code, as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183).

data/api/client-server/definitions/request_token_response.yaml

@@ -24,16 +24,23 @@ properties:
   submit_url:
     type: string
     format: uri
+    x-changedInMatrixVersion:
+      "1.18": |-
+        The URL has the same request and response parameters and error codes as
+        the Identity Service API's endpoint.
     description: |-
       An optional field containing a URL where the client must submit the
-      validation token to, with identical parameters to the Identity Service
-      API's `POST /validate/email/submitToken` endpoint (without the requirement
-      for an access token). The homeserver must send this token to the user (if
-      applicable), who should then be prompted to provide it to the client.
+      validation token, with identical request and response parameters and error
+      codes to the Identity Service API's
+      [`POST /validate/email/submitToken`](/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)
+      and [`POST /validate/msisdn/submitToken`](/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken)
+      endpoints (without the requirement for an access token). The homeserver
+      must send this token to the user (if applicable), who should then be
+      prompted to provide it to the client.
 
       If this field is not present, the client can assume that verification
       will happen without the client's involvement provided the homeserver
-      advertises this specification version in the `/versions` response
-      (ie: r0.5.0).
+      advertises a sufficiently recent version in the [`GET /versions`](/client-server-api/#get_matrixclientversions)
+      response (ie: r0.5.0).
     example: "https://example.org/path/to/submitToken"
 required: ['sid']

data/api/identity/v2_email_associations.yaml

@@ -153,6 +153,24 @@ paths:
                   value: {
                     "success": true
                   }
+        "400":
+          description: |
+            An error occurred. Some possible errors are:
+
+            - {{% added-in v="1.18" %}} `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is
+              incorrect.
+            - {{% added-in v="1.18" %}} `M_INVALID_PARAM`: One of the supplied parameters is not valid.
+            - {{% added-in v="1.18" %}} `M_SESSION_EXPIRED`: The validation session in question has expired.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOKEN_INCORRECT",
+                    "error": "The token is incorrect"
+                  }
         "403":
           description: |
             The user must do something in order to use this endpoint. One example

data/api/identity/v2_phone_associations.yaml

@@ -155,6 +155,24 @@ paths:
                   value: {
                     "success": true
                   }
+        "400":
+          description: |
+            An error occurred. Some possible errors are:
+
+            - {{% added-in v="1.18" %}} `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is
+              incorrect.
+            - {{% added-in v="1.18" %}} `M_INVALID_PARAM`: One of the supplied parameters is not valid.
+            - {{% added-in v="1.18" %}} `M_SESSION_EXPIRED`: The validation session in question has expired.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOKEN_INCORRECT",
+                    "error": "The token is incorrect"
+                  }
         "403":
           description: |
             The user must do something in order to use this endpoint. One example