Merge 205fa06076 into fda3be5ee3

changelogs/client_server/newsfragments/2212.clarification

@@ -0,0 +1 @@
+Add example to each endpoint when the capability is not available.

data/api/client-server/administrative_contact.yaml

@@ -180,6 +180,18 @@ paths:
                   value: {
                     "submit_url": "https://example.org/path/to/submitToken"
                   }
+        "400":
+          description: The 3PID changes capability is not available.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "3PID changes are disabled on this server."
+                  }
         "403":
           description: The credentials could not be verified with the identity server.
           content:
@@ -252,6 +264,18 @@ paths:
               examples:
                 response:
                   value: {}
+        "400":
+          description: The 3PID changes capability is not available.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "3PID changes are disabled on this server."
+                  }
         "401":
           description: The homeserver requires additional authentication information.
           content:
@@ -401,6 +425,18 @@ paths:
                     example: success
                 required:
                   - id_server_unbind_result
+        "400":
+          description: The 3PID changes capability is not available.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "3PID changes are disabled on this server."
+                  }
       tags:
         - Account management
   /account/3pid/unbind:

data/api/client-server/login_token.yaml

@@ -110,6 +110,18 @@ paths:
             application/json:
               schema:
                 $ref: definitions/auth_response.yaml
+        "404":
+          description: The get login token capability is not available.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNRECOGNIZED",
+                    "error": "The get login token capability is not available."
+                  }
         "429":
           description: This request was rate-limited.
           content:

data/api/client-server/password_management.yaml

@@ -86,6 +86,18 @@ paths:
             application/json:
               schema:
                 $ref: definitions/auth_response.yaml
+        "403":
+          description: The password change capability is not available.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Password change is disabled."
+                  }
         "429":
           description: This request was rate-limited.
           content:

data/api/client-server/profile.yaml

@@ -121,6 +121,12 @@ paths:
                       "errcode": "M_INVALID_PARAM",
                       "error": "Invalid profile key.",
                     }
+                capability_disabled:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile modification is disabled on this homeserver.",
+                    }
         "403":
           description: The server is unwilling to perform the operation, either
             due to insufficient permissions or because profile modifications