Added section on rate limiting.

1 files changed, 15 insertions, 3 deletions

diff --git a/docs/specification.rst b/docs/specification.rst

index 0ef18aab68..1e472d46bf 100644
--- a/docs/specification.rst
+++ b/docs/specification.rst
@@ -1402,11 +1402,24 @@ SRV Records
 
 Security
 ========
-- rate limiting
-
 .. NOTE::
   This section is a work in progress.
 
+Rate limiting
+-------------
+Home servers SHOULD implement rate limiting to reduce the risk of being overloaded. If a
+request is refused due to rate limiting, it should return a standard error response of
+the form::
+
+  {
+    "errcode": "M_LIMIT_EXCEEDED",
+    "error": "string",
+    "retry_after_ms": integer (optional)
+  }
+
+The ``retry_after_ms`` key SHOULD be included to tell the client how long they have to wait
+in milliseconds before they can try again.
+
 .. TODO
   - crypto (s-s auth)
   - E2E
@@ -1499,4 +1512,3 @@ User ID:
 .. _/join/<room_alias_or_id>: /-rooms/join
 
 .. _`Event Stream`: /-events/get_event_stream
-.. _`Initial Sync`: /-events/initial_sync