One of the Additional HTTP Status Codes (RFC6585) is
Where can I find examples of HTTP / REST API Rate-Limiting HTTP response headers useful with this HTTP response status?
Asked
Active
Viewed 8.1k times
98
-
1Also, the way to use these headers is different. `response.headers["x-ratelimit-limit"]` – Manish Dec 07 '15 at 17:59
2 Answers
152
Here are some examples of HTTP API Rate Limiting HTTP Response headers. Taken from four common REST APIs: Github, Vimeo, Twitter and Imgur:
Github Rate Limiting http://developer.github.com/v3/#rate-limiting
#=============================#=============================================#
# HTTP Header # Description #
#=============================#=============================================#
| X-RateLimit-Limit | Request limit per hour |
+-----------------------------+---------------------------------------------+
| X-RateLimit-Remaining | The number of requests left for the time |
| | window |
+-----------------------------+---------------------------------------------+
Vimeo Rate Limiting http://developer.vimeo.com/guidelines/rate-limiting
#=============================#=============================================#
# HTTP Header # Description #
#=============================#=============================================#
| X-RateLimit-Limit | Request limit per day / per 5 minutes |
+-----------------------------+---------------------------------------------+
| X-RateLimit-Remaining | The number of requests left for the time |
| | window |
+-----------------------------+---------------------------------------------+
| X-RateLimit-Reset | The remaining window before the rate limit |
| | resets in UTC epoch seconds |
+-----------------------------+---------------------------------------------+
Twitter REST API Rate Limiting https://dev.twitter.com/docs/rate-limiting/1.1
Note: Twitter uses headers with similar names like Vimeo, but has another dash in each name.
#=============================#=============================================#
# HTTP Header # Description #
#=============================#=============================================#
| X-Rate-Limit-Limit | The rate limit ceiling for that given |
| | request |
+-----------------------------+---------------------------------------------+
| X-Rate-Limit-Remaining | The number of requests left for the |
| | 15 minute window |
+-----------------------------+---------------------------------------------+
| X-Rate-Limit-Reset | The remaining window before the rate limit |
| | resets in UTC epoch seconds |
+-----------------------------+---------------------------------------------+
Imgur API Rate Limits http://api.imgur.com/
#=============================#=============================================#
# HTTP Header # Description #
#=============================#=============================================#
| X-RateLimit-UserLimit | Total credits that can be allocated |
+-----------------------------+---------------------------------------------+
| X-RateLimit-UserRemaining | Total credits available |
+-----------------------------+---------------------------------------------+
| X-RateLimit-UserReset | Timestamp (unix epoch) for when the credits |
| | will be reset |
+-----------------------------+---------------------------------------------+
| X-RateLimit-ClientLimit | Total credits that can be allocated for the |
| | application in a day |
+-----------------------------+---------------------------------------------+
| X-RateLimit-ClientRemaining | Total credits remaining for the application |
| | in a day |
+-----------------------------+---------------------------------------------+
hakre
- 193,403
- 52
- 435
- 836
M8R-1jmw5r
- 4,896
- 2
- 18
- 26
-
14If you're designing your own rate-limit headers, the Best Current Practice BCP178 is a relevant resource, recommending that the X- prefix be deprecated. Check out the original RFC/BCP for more info. http://tools.ietf.org/html/bcp178 – 10gistic Dec 16 '14 at 02:43
-
Great examples, I made a Node.js package that can be used with the `request` package: https://github.com/webjay/x-rate – webjay Jun 09 '15 at 16:33
37
In addition to API specific headers, don't forget the humble, standard Retry-After header
Servers send the "Retry-After" header field to indicate how long the user agent ought to wait before making a follow-up request.... The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.
The standard makes specific additional recommendations when using it with a 503 or 3xx status code:
When sent with a 503 (Service Unavailable) response, Retry-After indicates how long the service is expected to be unavailable to the client. When sent with any 3xx (Redirection) response, Retry-After indicates the minimum time that the user agent is asked to wait before issuing the redirected request.
-
See also http://stackoverflow.com/questions/3764075/retry-after-http-response-header-does-it-affect-anything – Raedwald May 24 '13 at 14:24
-
3`Retry-After` is intended to be used with `503` or `30x` responses https://tools.ietf.org/html/rfc7231#section-7.1.3 – Russbear Apr 25 '16 at 17:30
-
4@Russbear but nothing in that section indicates it can't be used with other response codes. – Raedwald Apr 25 '16 at 19:16
-
28429 Too Many Requests: "The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request." https://tools.ietf.org/html/rfc6585#section-4 – MRA May 12 '17 at 13:00