Merge pull request #445 from Mashape/retries

docs(retries) document the retries setting

app/docs/0.10.x/proxy.md

@@ -36,7 +36,8 @@ service depending on their headers, URI, and HTTP method.
     - [1. Load balancing][proxy-load-balancing]
     - [2. Plugins execution][proxy-plugins-execution]
     - [3. Proxying & upstream timeouts][proxy-proxying-upstream-timeouts]
-    - [4. Response][proxy-response]
+    - [4. Errors & retries][proxy-retries]
+    - [5. Response][proxy-response]
 - [Configuring a fallback API][proxy-configuring-a-fallback-api]
 - [Configuring SSL for an API][proxy-configuring-ssl-for-an-api]
     - [The `https_only` property][proxy-the-https-only-property]
@@ -598,7 +599,31 @@ More information on this topic is covered in the
 
 [Back to TOC](#table-of-contents)
 
-#### 4. Response
+#### 4. Errors & retries
+
+Whenever an error occurs during while proxying, Kong will use the underlying
+Nginx mechanism [retries][ngx-http-proxy-retries] to pass the request on to
+the next upstream.
+
+There are two configurable elements here:
+
+1. The number of retries: this can be configured per API using the `retries`
+   property of the `API` object. See the [management API][API] for more
+   details on this.
+
+2. What exactly constitutes an error: here Kong uses the Nginx defaults, which
+   means an error or timeout occuring while establishing a connection with the
+   server, passing a request to it, or reading the response header.
+
+The second option is based on Nginx's [proxy_next_upstream][proxy_next_upstream]
+directive. This option is not directly configurable through Kong, but can be
+added using a custom Nginx configuration. See the
+[configuration reference][configuration-reference] for more details.
+
+
+[Back to TOC](#table-of-contents)
+
+#### 5. Response
 
 Kong receives the response from the upstream service and send it back to the
 downstream client in a streaming fashion. At this point Kong will execute
@@ -819,4 +844,5 @@ topic we just covered.
 [API]: /docs/{{page.kong_version}}/admin-api
 
 [ngx-http-proxy-module]: http://nginx.org/en/docs/http/ngx_http_proxy_module.html
+[ngx-http-proxy-retries]: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_tries
 [SNI]: https://en.wikipedia.org/wiki/Server_Name_Indication