Rate limiting in OpenAPI
Rate limiting is the art of trying to protect the API by telling “overactive” API consumers to calm down a bit, telling clients to reduce the frequency of their requests, or take a break entirely and come back later to avoid overwhelming the API.
Learn more about rate limiting over here.
Rate limiting error response
When a client exceeds the rate limit, the API should respond with a 429 Too Many Requests
status code.
This status code indicates that the user has sent too many requests in a given amount of time, and the error message can explain
that more clearly, especially when using quality error responses.
This response describes an error that looks like this:
Describing the 429
response in OpenAPI is important for communicating to API
consumers that there is rate limiting in place, if its been missed elsewhere or
if its only available on some endpoints, this is a good chance to make it clear.
Retry-After header
The Retry-After
header is a standard HTTP header that can be included in the
response to indicate how long the client should wait before making another
request. This header can be included in the 429 Too Many Requests
response to
inform the client about the time they should wait before retrying.
With this header added and a more specific error detail added, the response looks more like this.
Learn more about retries over here.
Rate limiting headers
Rate limiting headers are HTTP headers that provide information about the rate
limit status of the API. These headers can be included in the success response
unlike Retry-After
which goes on the error. They inform the client about
their current rate limit status, including the number of requests remaining, the
time until the rate limit resets, and the total number of requests allowed.
The following headers are commonly used for rate limiting, even if they are non-standard, but they show how to implement them in OpenAPI:
This response describes a successful request with rate limiting headers included.
Rate limiting headers draft RFC
The X-RateLimit-*
headers are not standard HTTP headers, and they are not
defined in any RFC. A new RateLimit header draft
RFC
This draft RFC outlines a new RateLimit
header to replace all of the
X-RateLimit-*
headers, and with a single header it can provide information
about the rate limit status of the API, including the number of requests
remaining, the time until the rate limit resets, and the total number of
requests allowed.
The following example shows a RateLimit
header with a policy named “default”,
which has another 50 requests allowed in the next 30 seconds.
The RateLimit
header focuses on the current state of the various quotes, but
it doesn’t provide information about the policy itself. The same draft RFC also
outlines a RateLimit-Policy
header which can be used to provide information
about how the policy works.
This example shows two policies, “default” and “daily”. The “default” policy has a quota of 100 requests and a window of 30 seconds, while the “daily” policy has a quota of 1000 requests and a window of 86400 seconds (24 hours).
Trying to describe these headers in OpenAPI is a bit tricky, as the syntax moves beyond
the simple key: value
pairs that OpenAPI is used to. The following example shows
how to describe the RateLimit
header in OpenAPI, using a string with a
pattern
to validate the format of the header value.
This example uses a regular expression to validate the format of the RateLimit
header value, which is a string that contains the policy name, the number of
requests remaining, and the time until the rate limit resets. The pattern
field is used to specify the regular expression that the header value must
match. The example
field is used to provide an example of the header value,
which is a string that contains the policy name, the number of requests
remaining, and the time until the rate limit resets.
The RateLimit-Policy
header can be described in a similar way, using a string
with a pattern
to validate the format of the header value.
This example uses a regular expression to validate the format of the
RateLimit-Policy
header value, which is a string that contains the policy name,
the quota of requests, and the window of time. The pattern
field is used to
specify the regular expression that the header value must match. The example
field is used to provide an example of the header value, which is a string that
contains the policy name, the quota of requests, and the window of time.
If these headers are being used, it might be easiest to provide some simple examples in the operation definitions, and dedicate a more specific “Rate Limiting Guide” somewhere in the API documentation to explain it all more fully elsewhere.
Last updated on