From 9f94b11d4c9e3f87a06c976cffb69d3b9a9d59a4 Mon Sep 17 00:00:00 2001
From: Kegan Dougal <kegan@matrix.org>
Date: Tue, 2 Sep 2014 17:51:45 +0100
Subject: [PATCH] Added section on rate limiting.

---
 docs/specification.rst | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/docs/specification.rst b/docs/specification.rst
index 0ef18aab6..1e472d46b 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