98

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?

1
  • 1
    Also, the way to use these headers is different. response.headers["x-ratelimit-limit"]
    – Manish
    Dec 7, 2015 at 17:59

2 Answers 2

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                                    |
+-----------------------------+---------------------------------------------+
2
  • 14
    If 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. tools.ietf.org/html/bcp178
    – 10gistic
    Dec 16, 2014 at 2:43
  • Great examples, I made a Node.js package that can be used with the request package: github.com/webjay/x-rate
    – webjay
    Jun 9, 2015 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.

4

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.