It isn’t well documented because:
- it is a bit hacky, the new rate limiter was set up to workaround issues we had with previous system
- it is temporary, we want to move to something much sturdier
- it may change at any moment (non-stable)
That said, i can clarify the meaning of those headers, as it may help people to understand what is happening:
X-RateLimit-Limit: the rate limit ceiling
X-RateLimit-Remaining: the number of requests left for the 2 seconds window
X-RateLimit-Reset: the remaining window before the rate limit resets, in UTC epoch seconds
X-RateLimit-Zone: the zone applied for this rate limit
Currently we have a global zone, if you get 503s with
X-RateLimit-Zone: global it means basically our servers are overloaded and reducing your rate will only help us but not necessarily you.
X-RateLimit-Zone value is
per-ip, it means we get too many requests from this IP.
Retrying your request before
X-RateLimit-Reset time is very likely to fail.
X-RateLimit-Remaining indicates how may requests are still allowed during this 2 seconds window. If the value is near