add documentation about the rate limiter behaviour

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.