From 76163d05c0f850f2ecaf6168247fded7149221b9 Mon Sep 17 00:00:00 2001
From: Peter Johnson <insomnia@rcpt.at>
Date: Tue, 13 Oct 2015 15:22:31 +0200
Subject: [PATCH] documentation for http status codes

---
 http-status-codes.md | 19 +++++++++++++++++++
 index.md             |  1 +
 2 files changed, 20 insertions(+)
 create mode 100644 http-status-codes.md

diff --git a/http-status-codes.md b/http-status-codes.md
new file mode 100644
index 0000000..97e14eb
--- /dev/null
+++ b/http-status-codes.md
@@ -0,0 +1,19 @@
+# HTTP status codes
+
+## Geocoding
+
+The following status codes are returned from the geocoding service:
+
+- `200 OK`: The request has succeeded.
+- `400 Bad Request`: An input parameter was invalid. An error message is included in the response body with more details.
+- `404 Not Found`: The URL is invalid or the path is no longer valid.
+- `408 Request Timeout`: The Elasticsearch cluster took too long to respond.
+- `500 Internal Server Error`: Generic fatal error.
+- `502 Bad Gateway`: Connection was lost to the Elasticsearch cluster.
+
+In all cases above, the response body will be valid geoJSON.
+
+## Rate limiter
+The rate limiter returns the status codes `403 Forbidden` and `429 Too Many Requests`.
+
+See [API keys and rate limits](/api-keys-rate-limits.md) for more information.
diff --git a/index.md b/index.md
index 89e9161..be2e0df 100644
--- a/index.md
+++ b/index.md
@@ -6,6 +6,7 @@ These pages offer an introduction to the API and terminology used in Mapzen Sear
 
 - [Get started](/get-started.md)
  - [API keys and rate limits](/api-keys-rate-limits.md)
+ - [HTTP status codes](/http-status-codes.md)
  - [`/search` endpoint: finding places](/search.md)
  - [`/autocomplete` endpoint](/autocomplete.md)
  - [`/reverse` endpoint: from point to place](/reverse.md)