From 064e8f1411be3468d1dcbd314f94edc115481604 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Fri, 19 Dec 2025 11:19:42 +0100
Subject: [PATCH] Spec Additional Error Codes for submitToken endpoint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../definitions/request_token_response.yaml   | 18 ++++++++++++------
 data/api/identity/v2_email_associations.yaml  | 19 +++++++++++++++++++
 data/api/identity/v2_phone_associations.yaml  | 19 +++++++++++++++++++
 3 files changed, 50 insertions(+), 6 deletions(-)

diff --git a/data/api/client-server/definitions/request_token_response.yaml b/data/api/client-server/definitions/request_token_response.yaml
index 0f8c8cab..2f4216aa 100644
--- a/data/api/client-server/definitions/request_token_response.yaml
+++ b/data/api/client-server/definitions/request_token_response.yaml
@@ -24,16 +24,22 @@ 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 /_matrix/identity/v2/validate/email/submitToken`](/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)
+      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.
 
       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 this specification version in the [`GET /versions`](/client-server-api/#get_matrixclientversions)
+      response (ie: r0.5.0).
     example: "https://example.org/path/to/submitToken"
 required: ['sid']
diff --git a/data/api/identity/v2_email_associations.yaml b/data/api/identity/v2_email_associations.yaml
index 81f4486c..e37c9725 100644
--- a/data/api/identity/v2_email_associations.yaml
+++ b/data/api/identity/v2_email_associations.yaml
@@ -153,6 +153,25 @@ paths:
                   value: {
                     "success": true
                   }
+        "400":
+          x-addedInMatrixVersion: "1.18"
+          description: |
+            An error occurred. Some possible errors are:
+
+            - `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is
+              incorrect.
+            - `M_INVALID_PARAM`: One of the supplied parameters is not valid.
+            - `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
diff --git a/data/api/identity/v2_phone_associations.yaml b/data/api/identity/v2_phone_associations.yaml
index b985a972..047cbc40 100644
--- a/data/api/identity/v2_phone_associations.yaml
+++ b/data/api/identity/v2_phone_associations.yaml
@@ -155,6 +155,25 @@ paths:
                   value: {
                     "success": true
                   }
+        "400":
+          x-addedInMatrixVersion: "1.18"
+          description: |
+            An error occurred. Some possible errors are:
+
+            - `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is
+              incorrect.
+            - `M_INVALID_PARAM`: One of the supplied parameters is not valid.
+            - `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