Add documentation for RateLimit-* throttle headers

Issue https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/731

doc/security/rack_attack.md

@@ -54,11 +54,7 @@ By default, protected paths are:
 - `/import/github/personal_access_token`
 - `/admin/session`
 
-This header is included in responses to blocked requests:
-
-```plaintext
-Retry-After: 60
-```
+See [User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md#response-headers) for the headers responded to blocked requests.
 
 For example, the following are limited to a maximum 10 requests per minute:
 

doc/user/admin_area/settings/protected_paths.md

@@ -28,11 +28,7 @@ GitLab rate limits the following paths with Rack Attack by default:
 GitLab responds with HTTP status code `429` to POST requests at protected paths
 that exceed 10 requests per minute per IP address.
 
-This header is included in responses to blocked requests:
-
-```plaintext
-Retry-After: 60
-```
+See [User and IP rate limits](../../admin_area/settings/user_and_ip_rate_limits.md#response-headers) for the headers responded to blocked requests.
 
 For example, the following are limited to a maximum 10 requests per minute:
 

doc/user/admin_area/settings/user_and_ip_rate_limits.md

@@ -36,6 +36,24 @@ Retry later
 
 It is possible to customize this response text in the admin area.
 
+## Response headers
+
+When a client exceeds the associated rate limit, the following requests are
+blocked. The server may respond with rate-limiting information allowing the
+requester to retry after a specific period of time. These information are
+attached into the response headers.
+
+| Header                | Example                         | Description                                                                                                                                                                                                             |
+|:----------------------|:--------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `RateLimit-Name`      | `throttle_authenticated_web`    | Name of the throttle the requests are blocked. [This section](#trying-out-throttling-settings-before-enforcing them).                                                                                                   |
+| `RateLimit-Limit`     | `60`                            | Indicate the request quota associated to the client in **1 minute**. If the rate limit period set in the admin area is different from 1 minute, the value of this header is adjusted to 60-minute period approximately. |
+| `RateLimit-Observed`  | `67`                            | Indicate the current request amount associated to the client in the time window                                                                                                                                         |
+| `RateLimit-Remaining` | `0`                             | Indicate the remaining quota in the time window. It is the result of RateLimit-Limit - RateLimit-Remaining.                                                                                                             |
+| `Retry-After`         | `30`                            | Indicate the remaining duration **in seconds** until the quota is reset. This is a [standardized HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After)                                    |
+| `RateLimit-Reset`     | `30`                            | An alias of `Retry-After` header                                                                                                                                                                                        |
+| `RateLimit-ResetTime` | `Tue, 05 Jan 2021 11:00:00 GMT` | The point of time in the future that the quest quota is reset. This header is formated as specified in [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3.1)                                                     |
+
+
 ## Use an HTTP header to bypass rate limiting
 
 > [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/622) in GitLab 13.6.

doc/user/gitlab_com/index.md

@@ -532,13 +532,7 @@ endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md).
 
 ### Rate limiting responses
 
-The [`Retry-After`
-header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After)
-indicates when the client should retry.
-
-Rate limits applied by HAProxy (instead of Cloudflare or the
-GitLab application) have `RateLimit-Reset` and `RateLimit-ResetTime`
-headers.
+Please see [list of the headers responded to blocked requests](../admin_area/settings/user_and_ip_rate_limits.md#response-headers) and [customizable response text](../admin_area/settings/user_and_ip_rate_limits.md#response-text) for more information.
 
 ### Protected paths throttle
 
@@ -548,11 +542,7 @@ paths that exceed 10 requests per **minute** per IP address.
 See the source below for which paths are protected. This includes user creation,
 user confirmation, user sign in, and password reset.
 
-This header is included in responses to blocked requests:
-
-```plaintext
-Retry-After: 60
-```
+[User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md#response-headers) includes a list of the headers responded to blocked requests.
 
 See [Protected Paths](../admin_area/settings/protected_paths.md) for more details.