We limit requests using rate-limiting keys. All routes that share the same rate-limiting key will also share the same quota.
Rate-limiting keys can use a combination of different properties to set a quota. For example:
session- This is the simplest key, and limits calls on a per-customer basis.
session_device- Limits calls per customer and per target device.
session_pop- Limits calls per customer and per destination location (the POP in which the target device is located).
Time window for limits
The window for quotas can be a minute, an hour, or a day. Our quotas are all currently set on a per-minute basis, or 60 seconds.
Sliding window calculation
We enforce rate limits using a “sliding window” algorithm.
(last_fixed_window_requests * last_window_weight) + current_fixed_window_requests <= api_limit
This algorithm “slides” a relative time frame across fixed time frames.
- Fixed window - 60 seconds as read from the system clock (HH:MM:00 to HH:MM:59).
- Relative window - The past 60 seconds.
Weight of the last minute
This answers the question, “Of the last 60 seconds, what percentage happened before the seconds on the clock (HH:MM:SS) read 00?”
We can figure this out using a simple formula:
(60 - seconds_in_current_clock_minute)/60
If the time is 11:28:25, then we are 25 seconds into the current clock minute (i.e. our fixed window):
(60 - 25)/60 35/60 = 0.583
In other words, 0.583 (or 58.3%) of the last 60 seconds happened before the clock rolled over into a new minute.
Last window’s requests
Again, we’ll use 11:28:25 as our time, so the weight of the last minute is 0.583.
We check our API counter to see how many requests the key/route received in the previous clock minute (11:27:00 to 11:27:59).
For the purpose of this example, we’ll say there were 12 requests.
(12 * 0.583) + current_fixed_window_requests <= api_limit
Current window’s requests
We check how many requests have been sent during the current clock minute (11:28:00 to 11:28:25). We’ll say there have been 5 requests.
(12 * 0.583) + 5 <= api_limit
Putting it all together
Finally, let’s say the API requests are limited to 15 per minute.
(12 * 0.583) + 5 6.996 + 5 = 11.996 11.996 <= 15 returns true
The limit has not been reached, so the request is allowed.
Exceeded limits and rate limit headers
Should the rate limit be exceeded, you will get a
429 — Too Many Requests response error.
The response body will also tell you the applicable rate limit in the format
X per (minute|hour|day).
To make it easier to comply with these limits, every request to a rate-limited route will return a response with headers that provide information about the rate limit, window, and remaining quota.
These headers are:
X-RateLimit-Limit- An integer value representing the defined limit.
X-RateLimit-Remaining- A float value representing the remaining quota.
X-RateLimit-Window- A string value of
Can I increase my quota?
This is not currently possible, but we have development plans to allow this.