diff --git a/api/client-server/v1/definitions/error.yaml b/api/client-server/v1/definitions/error.yaml
index 5a5587ab..20312ae4 100644
--- a/api/client-server/v1/definitions/error.yaml
+++ b/api/client-server/v1/definitions/error.yaml
@@ -1,7 +1,10 @@
 type: object
+description: A Matrix-level Error
 properties:
   errcode:
     type: string
+    description: An error code.
   error:
     type: string
+    description: A human-readable error message.
 required: ["errcode"]
\ No newline at end of file
diff --git a/api/client-server/v1/profile.yaml b/api/client-server/v1/profile.yaml
index d0343a2c..99507186 100644
--- a/api/client-server/v1/profile.yaml
+++ b/api/client-server/v1/profile.yaml
@@ -44,6 +44,10 @@ paths:
           description: The display name was set.
           schema:
             type: object  # empty json object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
     get:
       summary: Get the user's display name.
       parameters:
@@ -89,6 +93,10 @@ paths:
           description: The avatar URL was set.
           schema:
             type: object  # empty json object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
     get:
       summary: Get the user's avatar URL.
       parameters: