From bd24f6262319d844704c2863574b5fb9e469ad7c Mon Sep 17 00:00:00 2001
From: Param Singh <param@metabrainz.org>
Date: Mon, 3 Jun 2019 23:00:30 +0530
Subject: [PATCH] Add documentation for API ratelimiting

---
 docs/api.rst | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/docs/api.rst b/docs/api.rst
index 4eb9d3d40..73ced2331 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -23,3 +23,31 @@ Datasets
    :blueprints: api_v1_datasets
    :include-empty-docstring:
    :undoc-static:
+
+Rate limiting
+^^^^^^^^^^^^^
+
+The AcousticBrainz API is rate limited via the use of rate limiting headers that
+are sent as part of the HTTP response headers. Each call will include the
+following headers:
+
+- **X-RateLimit-Limit**: Number of requests allowed in given time window
+
+- **X-RateLimit-Remaining**: Number of requests remaining in current time
+  window
+
+- **X-RateLimit-Reset-In**: Number of seconds when current time window expires
+  (*recommended*: this header is resilient against clients with incorrect
+  clocks)
+
+- **X-RateLimit-Reset**: UNIX epoch number of seconds (without timezone) when
+  current time window expires [#]_
+
+Rate limiting is automatic and the client must use these headers to determine
+the rate to make API calls. If the client exceeds the number of requests
+allowed, the server will respond with error code ``429: Too Many Requests``.
+Requests that provide the *Authorization* header with a valid user token may
+receive higher rate limits than those without valid user tokens.
+
+.. [#] Provided for compatibility with other APIs, but we still recommend using
+   ``X-RateLimit-Reset-In`` wherever possible