diff --git a/api/application-service/application_service.yaml b/api/application-service/application_service.yaml
index 43a6023b..b459e29f 100644
--- a/api/application-service/application_service.yaml
+++ b/api/application-service/application_service.yaml
@@ -131,7 +131,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
@@ -140,7 +140,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         404:
           description: |-
             The application service indicates that this room alias does not exist.
@@ -150,7 +150,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
   "/users/{userId}":
     get:
       summary: Query if a user should exist on the application service.
@@ -187,7 +187,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
@@ -196,7 +196,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         404:
           description: |-
             The application service indicates that this user does not exist.
@@ -206,7 +206,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
   "/_matrix/app/unstable/thirdparty/protocol/{protocol}":
     get:
       summary: Retrieve metadata about a specific protocol that the application service supports.
@@ -236,7 +236,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
@@ -245,7 +245,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         404:
           description: No protocol was found with the given path.
           examples:
@@ -253,7 +253,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
   "/_matrix/app/unstable/thirdparty/user/{protocol}":
     get:
       summary: Retrieve the Matrix User ID of a corresponding third party user.
@@ -289,7 +289,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
@@ -298,7 +298,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         404:
           description: No users were found with the given parameters.
           examples:
@@ -306,7 +306,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
   "/_matrix/app/unstable/thirdparty/location/{protocol}":
     get:
       summary: Retreive Matrix-side portal rooms leading to a third party location.
@@ -340,7 +340,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
@@ -349,7 +349,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         404:
           description: No mappings were found with the given parameters.
           examples:
@@ -357,7 +357,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
   "/_matrix/app/unstable/thirdparty/location":
     get:
       summary: Reverse-lookup third party locations given a Matrix room alias.
@@ -385,7 +385,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
@@ -394,7 +394,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         404:
           description: No mappings were found with the given parameters.
           examples:
@@ -402,7 +402,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
   "/_matrix/app/unstable/thirdparty/user":
     get:
       summary: Reverse-lookup third party users given a Matrix User ID.
@@ -429,7 +429,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         403:
           description: |-
             The credentials supplied by the homeserver were rejected.
@@ -438,7 +438,7 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
+            $ref: ../client-server/definitions/errors/error.yaml
         404:
           description: No mappings were found with the given parameters.
           examples:
@@ -446,4 +446,4 @@ paths:
               "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
             }
           schema:
-            $ref: ../client-server/definitions/error.yaml
\ No newline at end of file
+            $ref: ../client-server/definitions/errors/error.yaml
\ No newline at end of file
diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml
index e7381a55..8f0319d5 100644
--- a/api/client-server/administrative_contact.yaml
+++ b/api/client-server/administrative_contact.yaml
@@ -129,6 +129,8 @@ paths:
                 "errcode": "M_THREEPID_AUTH_FAILED",
                 "error": "The third party credentials could not be verified by the identity server."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - User data
   "/account/3pid/email/requestToken":
diff --git a/api/client-server/banning.yaml b/api/client-server/banning.yaml
index 4030f46b..6ef430df 100644
--- a/api/client-server/banning.yaml
+++ b/api/client-server/banning.yaml
@@ -83,6 +83,8 @@ paths:
                 "errcode": "M_FORBIDDEN",
                 "error": "You do not have a high enough power level to ban from this room."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room membership
   "/rooms/{roomId}/unban":
@@ -134,5 +136,7 @@ paths:
                 "errcode": "M_FORBIDDEN",
                 "error": "You do not have a high enough power level to unban from this room."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room membership
diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml
index 34fe868b..b3e9517b 100644
--- a/api/client-server/content-repo.yaml
+++ b/api/client-server/content-repo.yaml
@@ -72,7 +72,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
   "/download/{serverName}/{mediaId}":
@@ -120,7 +120,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
   "/download/{serverName}/{mediaId}/{fileName}":
@@ -175,7 +175,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
   "/thumbnail/{serverName}/{mediaId}":
@@ -241,7 +241,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
   "/preview_url":
@@ -296,7 +296,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
   "/config":
@@ -336,7 +336,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/error.yaml"
 
       tags:
         - Media
diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml
index 37c8ec21..66b5578a 100644
--- a/api/client-server/create_room.yaml
+++ b/api/client-server/create_room.yaml
@@ -216,6 +216,8 @@ paths:
               invalid: for example, the user's ``power_level`` is set below
               that necessary to set the room name (``errcode`` set to
               ``M_INVALID_ROOM_STATE``).
+          schema:
+            "$ref": "definitions/errors/error.yaml"
 
       tags:
         - Room creation
diff --git a/api/client-server/definitions/error.yaml b/api/client-server/definitions/errors/error.yaml
similarity index 90%
rename from api/client-server/definitions/error.yaml
rename to api/client-server/definitions/errors/error.yaml
index fa5cada7..7471da6f 100644
--- a/api/client-server/definitions/error.yaml
+++ b/api/client-server/definitions/errors/error.yaml
@@ -17,7 +17,9 @@ properties:
   errcode:
     type: string
     description: An error code.
+    example: M_UNKNOWN
   error:
     type: string
     description: A human-readable error message.
+    example: An unknown error occurred
 required: ["errcode"]
\ No newline at end of file
diff --git a/api/client-server/definitions/errors/rate_limited.yaml b/api/client-server/definitions/errors/rate_limited.yaml
new file mode 100644
index 00000000..aca82ce7
--- /dev/null
+++ b/api/client-server/definitions/errors/rate_limited.yaml
@@ -0,0 +1,32 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+$ref: error.yaml
+type: object
+description: The rate limit was reached for this request
+properties:
+  errcode:
+    type: string
+    description: The M_LIMIT_EXCEEDED error code
+    example: M_LIMIT_EXCEEDED
+  error:
+    type: string
+    description: A human-readable error message.
+    example: Too many requests
+  retry_after_ms:
+    type: integer
+    description: |-
+      The amount of time in milliseconds the client should wait
+      before trying the request again.
+    example: 2000
+required: ["errcode"]
\ No newline at end of file
diff --git a/api/client-server/directory.yaml b/api/client-server/directory.yaml
index a50bab62..ee42cf84 100644
--- a/api/client-server/directory.yaml
+++ b/api/client-server/directory.yaml
@@ -68,6 +68,8 @@ paths:
                 "errcode": "M_UNKNOWN",
                 "error": "Room alias #monkeys:matrix.org already exists."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room directory
     get:
@@ -118,6 +120,8 @@ paths:
                 "errcode": "M_NOT_FOUND",
                 "error": "Room alias #monkeys:matrix.org not found."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room directory
     delete:
diff --git a/api/client-server/inviting.yaml b/api/client-server/inviting.yaml
index 47f51bd4..f312d5ce 100644
--- a/api/client-server/inviting.yaml
+++ b/api/client-server/inviting.yaml
@@ -93,9 +93,11 @@ paths:
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership
diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml
index 471c5038..7dc1e0a4 100644
--- a/api/client-server/joining.yaml
+++ b/api/client-server/joining.yaml
@@ -110,10 +110,12 @@ paths:
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership
   "/join/{roomIdOrAlias}":
@@ -215,9 +217,11 @@ paths:
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership
diff --git a/api/client-server/kicking.yaml b/api/client-server/kicking.yaml
index bacc806e..7fbee38b 100644
--- a/api/client-server/kicking.yaml
+++ b/api/client-server/kicking.yaml
@@ -87,5 +87,7 @@ paths:
                 "errcode": "M_FORBIDDEN",
                 "error": "You do not have a high enough power level to kick from this room."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room membership
diff --git a/api/client-server/leaving.yaml b/api/client-server/leaving.yaml
index 57a148c6..513b5b4d 100644
--- a/api/client-server/leaving.yaml
+++ b/api/client-server/leaving.yaml
@@ -64,7 +64,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership
   "/rooms/{roomId}/forget":
@@ -107,10 +107,10 @@ paths:
               "error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
             }
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership
diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml
index 334d528c..45034488 100644
--- a/api/client-server/list_public_rooms.yaml
+++ b/api/client-server/list_public_rooms.yaml
@@ -59,6 +59,8 @@ paths:
               "errcode": "M_NOT_FOUND",
               "error": "Room not found"
             }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
     put:
       summary: Sets the visibility of a room in the room directory
       description: |-
@@ -107,6 +109,8 @@ paths:
               "errcode": "M_NOT_FOUND",
               "error": "Room not found"
             }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
   "/publicRooms":
     get:
       summary: Lists the public rooms on the server.
diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml
index c0db2299..289b17e7 100644
--- a/api/client-server/login.yaml
+++ b/api/client-server/login.yaml
@@ -61,7 +61,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Session management
     post:
@@ -167,15 +167,19 @@ paths:
                   "errcode": "M_UNKNOWN",
                   "error": "Bad login type."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         403:
           description: |-
             The login attempt failed. For example, the password may have been incorrect.
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN"}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Session management
diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml
index 46134430..91b75c6a 100644
--- a/api/client-server/presence.yaml
+++ b/api/client-server/presence.yaml
@@ -75,7 +75,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Presence
     get:
@@ -123,6 +123,8 @@ paths:
           description: |-
             There is no presence state for this user. This user may not exist or
             isn't exposing presence information to you.
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         403:
           description: You are not allowed to see this user's presence status.
           examples:
@@ -131,7 +133,7 @@ paths:
               "error": "You are not allowed to see their presence"
             }
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/error.yaml"
       tags:
         - Presence
   "/presence/list/{userId}":
@@ -187,7 +189,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Presence
     get:
diff --git a/api/client-server/profile.yaml b/api/client-server/profile.yaml
index 0cada0ca..c8dc4056 100644
--- a/api/client-server/profile.yaml
+++ b/api/client-server/profile.yaml
@@ -67,7 +67,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
     get:
@@ -141,7 +141,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
     get:
diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml
index 9cf40a06..938014c6 100644
--- a/api/client-server/pusher.yaml
+++ b/api/client-server/pusher.yaml
@@ -228,10 +228,10 @@ paths:
                 "errcode": "M_MISSING_PARAM"
               }
           schema:
-            type: object
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Push notifications
diff --git a/api/client-server/pushrules.yaml b/api/client-server/pushrules.yaml
index 801349ef..ceb9954b 100644
--- a/api/client-server/pushrules.yaml
+++ b/api/client-server/pushrules.yaml
@@ -438,11 +438,11 @@ paths:
                 "errcode": "M_UNKNOWN"
               }
           schema:
-            type: object
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Push notifications
   "/pushrules/{scope}/{kind}/{ruleId}/enabled":
diff --git a/api/client-server/receipts.yaml b/api/client-server/receipts.yaml
index e46359a9..a3e9789e 100644
--- a/api/client-server/receipts.yaml
+++ b/api/client-server/receipts.yaml
@@ -76,6 +76,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room participation
diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index 1c544afe..6ae4ddd3 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -177,6 +177,8 @@ paths:
                   "errcode": "M_USER_IN_USE",
                   "error": "Desired user ID is already taken."
               }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         401:
           description: |-
             The homeserver requires additional authentication information.
@@ -185,7 +187,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
   "/register/email/requestToken":
@@ -249,7 +251,7 @@ paths:
                 "error": "The specified address is already in use"
               }
           schema:
-            type: object
+            "$ref": "definitions/errors/error.yaml"
   "/account/password":
     post:
       summary: "Changes a user's password."
@@ -296,7 +298,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
   "/account/password/email/requestToken":
@@ -363,7 +365,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
   "/register/available":
@@ -420,9 +422,11 @@ paths:
               "errcode": "M_USER_IN_USE",
               "error": "Desired user ID is already taken."
             }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml
index e28461c4..e4118c32 100644
--- a/api/client-server/search.yaml
+++ b/api/client-server/search.yaml
@@ -367,6 +367,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Search
diff --git a/api/client-server/third_party_lookup.yaml b/api/client-server/third_party_lookup.yaml
index efb4310f..55d4c70a 100644
--- a/api/client-server/third_party_lookup.yaml
+++ b/api/client-server/third_party_lookup.yaml
@@ -66,7 +66,7 @@ paths:
               "errcode": "M_NOT_FOUND"
             }
           schema:
-            $ref: definitions/error.yaml
+            $ref: definitions/errors/error.yaml
   "/thirdparty/location/{protocol}":
     get:
       summary: Retreive Matrix-side portals rooms leading to a third party location.
@@ -105,7 +105,7 @@ paths:
               "errcode": "M_NOT_FOUND"
             }
           schema:
-            $ref: definitions/error.yaml
+            $ref: definitions/errors/error.yaml
   "/thirdparty/user/{protocol}":
     get:
       summary: Retrieve the Matrix User ID of a corresponding third party user.
@@ -138,7 +138,7 @@ paths:
               "errcode": "M_NOT_FOUND"
             }
           schema:
-            $ref: definitions/error.yaml
+            $ref: definitions/errors/error.yaml
   "/thirdparty/location":
     get:
       summary: Reverse-lookup third party locations given a Matrix room alias.
@@ -165,7 +165,7 @@ paths:
               "errcode": "M_NOT_FOUND"
             }
           schema:
-            $ref: definitions/error.yaml
+            $ref: definitions/errors/error.yaml
   "/thirdparty/user":
     get:
       summary: Reverse-lookup third party users given a Matrix User ID.
@@ -191,4 +191,4 @@ paths:
               "errcode": "M_NOT_FOUND"
             }
           schema:
-            $ref: definitions/error.yaml
\ No newline at end of file
+            $ref: definitions/errors/error.yaml
\ No newline at end of file
diff --git a/api/client-server/third_party_membership.yaml b/api/client-server/third_party_membership.yaml
index 612b22d0..66c14c4d 100644
--- a/api/client-server/third_party_membership.yaml
+++ b/api/client-server/third_party_membership.yaml
@@ -126,9 +126,11 @@ paths:
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership
diff --git a/api/client-server/typing.yaml b/api/client-server/typing.yaml
index e2a8f9bd..e7cbe2d7 100644
--- a/api/client-server/typing.yaml
+++ b/api/client-server/typing.yaml
@@ -82,6 +82,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room participation
diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml
index 1734e3bb..a682b435 100644
--- a/api/client-server/users.yaml
+++ b/api/client-server/users.yaml
@@ -95,6 +95,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
diff --git a/api/client-server/voip.yaml b/api/client-server/voip.yaml
index 6d6136a5..75ace4c3 100644
--- a/api/client-server/voip.yaml
+++ b/api/client-server/voip.yaml
@@ -73,6 +73,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - VOIP
diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml
index 8f5abdf7..ad40eb86 100644
--- a/api/client-server/whoami.yaml
+++ b/api/client-server/whoami.yaml
@@ -65,7 +65,7 @@ paths:
               "error": "Unrecognised access token."
             }
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/error.yaml"
         403:
           description:
             The appservice cannot masquerade as the user or has not registered them.
@@ -75,10 +75,10 @@ paths:
               "error": "Application service has not registered this user."
             }
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data
diff --git a/changelogs/client_server/newsfragments/1373.clarification b/changelogs/client_server/newsfragments/1373.clarification
new file mode 100644
index 00000000..21e18966
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1373.clarification
@@ -0,0 +1 @@
+Describe the rate limit error response schema