Add example to each endpoint when the capability is not available

changelogs/client_server/newsfragments/2212.clarification

@@ -0,0 +1 @@
+Add note to each endpoint that uses capability negotiation and document expected response when the capability is not available.

data/api/client-server/administrative_contact.yaml

@@ -99,6 +99,10 @@ paths:
         has been removed, making this endpoint behave as though it was `false`.
         This results in this endpoint being an equivalent to `/3pid/bind` rather
         than dual-purpose.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
       operationId: post3PIDs
       deprecated: true
       security:
@@ -176,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:
@@ -202,6 +218,10 @@ paths:
         Homeservers should prevent the caller from adding a 3PID to their account if it has
         already been added to another user's account on the homeserver.
 
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
+
         {{% boxes/warning %}}
         Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
         via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
@@ -244,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:
@@ -331,6 +363,10 @@ paths:
         Unlike other endpoints, this endpoint does not take an `id_access_token`
         parameter because the homeserver is expected to sign the request to the
         identity server instead.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
       operationId: delete3pidFromAccount
       security:
         - accessTokenQuery: []
@@ -389,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

@@ -34,6 +34,10 @@ paths:
         valid access token is provided. The homeserver SHOULD NOT revoke the
         access token provided in the request. Whether other access tokens for
         the user are revoked depends on the request parameters.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.change_password` capability](/client-server-api/#mchange_password-capability)
+        to determine if this endpoint is available.
       security:
         - {}
         - accessTokenQuery: []
@@ -82,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

@@ -29,6 +29,11 @@ paths:
         Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
         them rather than treating `null` as a deletion request. Clients that want to delete a
         field, including its key and value, SHOULD use the `DELETE` endpoint instead.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation)
+        depending on the `keyName`.
+        For the `displayname` key, clients SHOULD check the value of the [`m.set_displayname` capability](/client-server-api/#mset_displayname-capability).
+        For the `avatar_url` key, clients SHOULD check the value of the [`m.set_avatar_url` capability](/client-server-api/#mset_avatar_url-capability).
       operationId: setProfileField
       security:
         - accessTokenQuery: []
@@ -116,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