Skip to content

Rate Limiting response headers

Problem

Customers do not get any sort of signal that they may be approaching hitting a rate limit. They only receive response headers after the limit has been reached and they have been blocked. This is also an inconsistent experience depending on where the rate limit happens (e.g. Cloudflare, Rack Attack, etc).

If customers had more visibility into rate limits prior to being blocked, it would enable us to shift further left as they may then be able to answer some of their own queries about their rate limits before needing to raise support issues.

There are many clients, such as the GitLab Terraform Provider and Go GitLab Client which may (if not already) be configured to respect RateLimit response headers, and configure exponential backoffs that will give customers a better user experience if we were to return these headers more consistently.

Solution

Where possible, we should consistently return RateLimit response headers to requests whether they are RateLimited or not.

Headers to consider (based on what we have in our documentation here):

Response Header Description / Comments
RateLimit-Limit The request quota for the client each minute.
RateLimit-Observed Number of requests associated to the client in the time window.
RateLimit-Remaining remaining quota in the time window (Limit - Observed).
RateLimit-Reset Unix time - When the request quota is reset.
RateLimit-ResetTime RFC2616 formatted time when the request quota is reset.
RateLimit-Name Name of the throttle blocking the requests (we say in the docs we return this, but it doesn't look like we do 🤔)
Retry-After A standard HTTP header for when the quota is reset.

Reference

Edited by Steve Abrams