Add HTTP 403 to possible profile responses (#3530)

* Add HTTP 403 to possible profile responses

Some servers may not allow profile lookup over federation, and thus
respond to GET /_matrix/client/v3/profile/{userId} with an HTTP 403.

For example, Synapse can be configured to behave in this way by setting:

    allow_profile_lookup_over_federation=false

Thus, this behavior already exists in the wild, and may cause issues for
clients such as https://github.com/vector-im/element-web/issues/17269.

Synapse could alter its behavior and return an HTTP 404 in these cases,
but amending the Spec seems preferable to align with extant behavior.
Further, allowing HTTP 403 gives clients more specific information as to
why a request has failed, enabling more precise error handling.

Signed-off-by: Dan Callahan <danc@element.io>

* Update changelogs/client_server/newsfragments/3530.clarification

Co-authored-by: Travis Ralston <travpc@gmail.com>

* Annotate misc data about error

Co-authored-by: Travis Ralston <travpc@gmail.com>
Co-authored-by: Travis Ralston <travisr@matrix.org>

changelogs/client_server/newsfragments/3530.clarification

@@ -0,0 +1 @@
+Add `403 M_FORBIDDEN` error code to `/profile/{userId}` as per [MSC3550](https://github.com/matrix-org/matrix-doc/pull/3550).

data/api/client-server/profile.yaml

@@ -211,7 +211,24 @@ paths:
               displayname:
                 type: string
                 description: The user's display name if they have set one, otherwise not present.
+        403:
+          x-addedInMatrixVersion: "1.2"
+          description: The server is unwilling to disclose whether the user exists and/or has profile information.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "Profile lookup over federation is disabled on this homeserver"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         404:
           description: There is no profile information for this user or this user does not exist.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "Profile not found"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - User data