Does Eratos Rate Limit API Requests?

Introduction

In order to ensure fair access to all resources for all users, HTTP request rate limiting is implemented across some public APIs. This is implemented using the HTTP standard 429 "Too Many Requests" response.

Each user account is provided a limited number of requests that can be made to any given API within a given time frame. When this quota is exceeded, an HTTP 429 response will be generated instead of the usual API response. Applications receiving a 429 response must cease making requests to the affected API until the quota is restored. It is strongly advised that subsequent requests be made at a reduced rate to avoid further rate-limiting responses.

The request quotas differ across each API in order to account for different levels of anticipated demand. In each case, quotas are defined as a specific number of requests permitted per user account per second, per minute, or per hour. In cases where an API defines multiple quota rates (i.e., a per-second quota and a per-minute quota), rate limiting will apply whenever one quota is exhausted, even if the other quota has not been exhausted.

Currently only the APIs listed below have rate limits applied.

API HTTP Endpoint Request Quotas

As a concrete example, a client may make up to 100 requests per second to the Sensor Data API but will be subject to rate limiting if doing so for more than ten seconds in any 60-second window, or if the request rate exceeds 100 requests per second (whichever occurs first). Even if making fewer than 100 requests per second, the client will be subject to rate limiting if over 1000 requests are received in a 60-second period.

Response Headers

The rate-limited APIs send some HTTP headers with each response to allow clients to know what quotas are in effect for each API and what the client's remaining quota is for the API. These headers can be used to intelligently throttle request rates to avoid rate limiting or to determine how long to wait before trying further requests if rate limiting occurs.

The HTTP response headers provided are as follows:

In the case that a client receives an HTTP 429 response, one or more of the X-RateLimit-Remaining headers will be zero.

Example Rate Limiting Algorithms

Ideally, it’s best to avoid generating rate limiting errors by proactively ensuring your application’s request rate remains below the rate limits for the service in question. In the simplest case—where only a few requests will be made or requests will be infrequent—it may be possible to simply make all requests as needed without worrying about rate limiting. However, in the case where many requests will be made, additional application logic will be required to either keep the effective request rate below the required limits or to “back off” the request rate when an HTTP 429 response is received.

More information on HTTP status 429 can be found here.

Please note that the following algorithms assume a single process making sequential requests. Distributed or multi threaded applications making multiple simultaneous requests will require more sophisticated rate limit handling.

Proactive Request Rate Management

A reasonable general approach to proactive rate limit management is to attempt to spread requests evenly in time so that the average request rate doesn't exceed whichever rate limit is most strict. The following algorithm can be used on a per-request basis to dynamically adjust the request rate, taking into account whichever rate limit is closest to being exceeded at the given point in time:

1. For each pair of X-RateLimit-Limit-XXX and X-RateLimit-Remaining-XXX headers in the response, compute:

score = remaining / limit

2. For the rate limit with the lowest score (i.e., closest to being exhausted):

• Let period be the corresponding time period (e.g., hour, minute, second).
• The time remaining until the quota resets can be estimated as:

  timeUntilReset = period * score

3. The next request shouldn't occur until a time period of:

timeUntilReset / remaining

Worked Example

Consider a response from the Analysis Service API after 30 requests have been made over a period of five seconds. Some possible rate limit header values in this case might be:

• X-RateLimit-Limit-Second = 100
• X-RateLimit-Remaining-Second = 94
• X-RateLimit-Limit-Minute = 300
• X-RateLimit-Remaining-Minute = 270

The score for the "second" rate limit is 94/100 = 0.94, and for the "minute" rate limit it is 270/300 = 0.90. The "minute" rate limit is closest to being exhausted. The time until reset (in seconds) can be estimated as:

timeUntilReset = 60 * 0.9 = 54 seconds

The next request should not occur until 54/270 = 0.2 seconds have elapsed.

Note: This example highlights two drawbacks of this approach:

1. Estimation Inaccuracy: The time remaining until quota reset is estimated from request counts instead of actual time. The estimate may not always be accurate, leading to occasional rate limiting errors.
2. Inefficiency: If the application only had a few more requests to make, it could potentially send them without delay. A more efficient implementation would take this into account.

Backing Off After HTTP 429 Response

After receiving an HTTP 429 response, a well-behaved application should wait a "back-off" period to allow the rate-limit quota to be refreshed before retrying its request. This avoids generating further 429 responses.

All HTTP 429 responses include the Retry-After response header, which specifies the number of seconds the application must wait before issuing further requests.

Disclaimers

• The rate limits listed for each API are subject to change for operational or security reasons.
• The limits are enforced on a best-effort basis, and excessively high request rates may exhaust quotas faster than expected.
• The response headers (X-RateLimit-*) should be considered authoritative. Where they differ from this documentation, the headers take precedence.

Further Reading & Information

• RFC 6585 §4 - 429 Too Many Requests
• HTTP Retry-After Header