Rate limiting your RESTful API

Seventh article in the series of “ Pragmatic decisions for your RESTful API”, this post talks about rate limiting for your RESTful API.

UPDATE February 13, 2023: Use the standard RateLimit-* headers and 429 status code

When I originally wrote this article in 2018, there was no standard header defined to return the rate limits of an API. However, as of now, in 2023, the IETF is currently in the process of publishing a standard for these headers. The document is still in draft (see https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/), but it will most probably at some point become a recognized standard. Therefore, I advise you to use the IETF standard, with the following headers:

• RateLimit-Limit: return the number of requests left for the client in the time window
• RateLimit-Remaining: return the remaining quota in the current window
• RateLimit-Reset: return the time remaining in the current window, specified in seconds
• RateLimit-Policy: return the quota policy. The quota policy expression can be found in paragraph 2.1 of the IETF draft. The format is, for example, for 100 requests in 60 seconds:

RateLimit-Policy: 100;w=60

The rest of the article as it was published in 2018 is still below, but consider the above paragraph as a better decision to make when rate limiting your RESTful API.

Rate limiting: use X-RateLimit-* HTTP headers and 429 status code

Rate limiting becomes necessary when your API starts becoming used by a wide range of applications and users.

When a rate limit is reached, your API should return the following HTTP status code:

429 Too Many Requests

Unfortunately however, there is no standard name for the HTTP headers you can use to inform users of the rate limits:

Twitter uses the following headers:

• X-Rate-Limit-Limit: the rate limit ceiling for that given endpoint
• 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

Github uses the following headers:

• X-RateLimit-Limit: The maximum number of requests you're permitted to make per hour.
• X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
• X-RateLimit-Reset: the time at which the current rate limit window resets in UTC epoch seconds

There seems to be, however, more RESTful API frameworks using Github’s standards than Twitter’s standards, which is why I advise you to use Github’s HTTP headers for rate limiting (ie X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset), with one exception.

Do not use Github’s standard for the X-RateLimit-Reset header. You can keep the same header name, but instead of showing a timestamp in the value of this header, show the number of seconds remaining before the rate limit resets.

Why ? Because the HTTP specification states that date formats should use the RFC 1123 (ie Fri, 09 Mar 2018 08:50:15 GMT). Hence, if you want to show a date in your X-RateLimit-Reset header, you should use this format instead of a timestamp, but it's much more practical to use the number of remaining seconds.

If you want to read all of the articles of the series “ Pragmatic decisions for your RESTful API”, you can start here. The next article will focus on authentication of your RESTful API.

This series of articles about Restful API design is also available as an eBook on Amazon, if you need it in a handy format.

Originally published at https://www.gvj-web.com on March 29, 2018.