From 473b365ec9d3b0a2af9a92172a12a19fa14eb128 Mon Sep 17 00:00:00 2001
From: Peter Johnson <insomnia@rcpt.at>
Date: Tue, 13 Oct 2015 14:57:22 +0200
Subject: [PATCH] add documentation about the rate limiter behaviour

---
 api-keys-rate-limits.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md
index 107d7b7..4b9ecff 100644
--- a/api-keys-rate-limits.md
+++ b/api-keys-rate-limits.md
@@ -18,5 +18,39 @@ Mapzen Search allows you a maximum of:
 
 If you need more capacity, contact [search@mapzen.com](mailto:search@mapzen.com). You can also set up your own instance of [Pelias](https://github.com/pelias/pelias), which has access to the same data used in Mapzen Search.
 
+## Failing to provide an `api_key`
+If you fail to supply the `api_key` parameter the service will respond with the status code `403 Forbidden`:
+```bash
+{
+  "meta": {
+    "version": 1,
+    "status_code": 403
+  },
+  "results": {
+    "error": {
+      "type": "KeyError",
+      "message": "No api_key specified."
+    }
+  }
+}
+```
+
+## Exceeding your limits
+If you exceed your limits the service will respond with the status code `429 Too Many Requests`:
+```bash
+{
+  "meta": {
+    "version": 1,
+    "status_code": 429
+  },
+  "results": {
+    "error": {
+      "type": "QpsExceededError",
+      "message": "Queries per second exceeded: Queries exceeded (6 allowed)."
+    }
+  }
+}
+```
+
 ## Security
 Mapzen Search works over HTTPS, in addition to HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information, such as a user's location or search query.