diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml
index f76b2fb9..7ded75d0 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}":
@@ -119,7 +119,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}":
@@ -173,7 +173,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}":
@@ -238,7 +238,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
   "/preview_url":
@@ -293,6 +293,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
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..6b4932ee
--- /dev/null
+++ b/api/client-server/definitions/errors/rate_limited.yaml
@@ -0,0 +1,26 @@
+# 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
+required: ["errcode"]
\ No newline at end of file
diff --git a/api/client-server/inviting.yaml b/api/client-server/inviting.yaml
index 47f51bd4..1e6694dc 100644
--- a/api/client-server/inviting.yaml
+++ b/api/client-server/inviting.yaml
@@ -96,6 +96,6 @@ paths:
         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 da4e4337..9890e73c 100644
--- a/api/client-server/joining.yaml
+++ b/api/client-server/joining.yaml
@@ -113,7 +113,7 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership
   "/join/{roomIdOrAlias}":
@@ -209,6 +209,6 @@ paths:
         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/leaving.yaml b/api/client-server/leaving.yaml
index 36351fd4..1a2515a6 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":
@@ -102,6 +102,6 @@ paths:
         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/login.yaml b/api/client-server/login.yaml
index c0db2299..e64ff953 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:
@@ -176,6 +176,6 @@ paths:
         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 ba202c2d..2a97e1ba 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:
@@ -176,7 +176,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..826b69d1 100644
--- a/api/client-server/pusher.yaml
+++ b/api/client-server/pusher.yaml
@@ -232,6 +232,6 @@ paths:
         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..22738c3e 100644
--- a/api/client-server/pushrules.yaml
+++ b/api/client-server/pushrules.yaml
@@ -442,7 +442,7 @@ paths:
         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..5c205999 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -185,7 +185,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":
@@ -296,7 +296,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 +363,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":
@@ -423,6 +423,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/search.yaml b/api/client-server/search.yaml
index e5f6a872..3dcd719f 100644
--- a/api/client-server/search.yaml
+++ b/api/client-server/search.yaml
@@ -355,6 +355,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_membership.yaml b/api/client-server/third_party_membership.yaml
index 612b22d0..3050ee3a 100644
--- a/api/client-server/third_party_membership.yaml
+++ b/api/client-server/third_party_membership.yaml
@@ -129,6 +129,6 @@ paths:
         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..4d178e07 100644
--- a/api/client-server/whoami.yaml
+++ b/api/client-server/whoami.yaml
@@ -79,6 +79,6 @@ paths:
         429:
           description: This request was rate-limited.
           schema:
-            "$ref": "definitions/error.yaml"
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - User data