Examples of HTTP API Rate Limiting HTTP Response headers
One of the Additional HTTP Status Codes (RFC6585) is
- 429 Too Many Requests
Where can I find examples of HTTP / REST API Rate-Limiting HTTP response headers that are useful with this HTTP response status?
Solution 1:
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 |
+-----------------------------+---------------------------------------------+
Solution 2:
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.