If API Rate Limits are enabled for your organization, some response headers are sent with each API response. The following response HTTP header fields enable servers to publish current request quotas and help you to shape your request policy and avoid getting throttled out.
Response Header | Description |
Api-RateLimit-Limit | Quota of total API requests (maximum limit) that can be allotted during each window. |
Organization-RateLimit-Limit | Quota of total organization-level requests (maximum limit) that can be allotted during each window. |
RateLimit-Limit | Quota of total requests that can be allotted during each window. |
RateLimit-Remaining | Quota of total requests that are remaining during a particular window. |
RateLimit-Reset | Remaining time in seconds until a particular window is reset. |
Retry-After | Time in seconds that you must wait before making a new request. |
Use Cases of Rate Limit Response Header Values
In this section, we will discuss the following three use cases of different rate limit response header values:
Use Case 1: when only organization (account)-level limit is defined
Use Case 2: when both organization (account)-level and API-level limits are defined
Use Case 1: when only organization (account)-level limit is defined
Consider a scenario where the organization (account)-level limit has been defined as follows:
Organization (account)-level quota is 60 calls per minute with a bucket capacity of 60.
In that scenario, assume that the server displays the following response headers about the current available limits:
Response
HTTP/1.1 200 Ok
Content-Type: application/json
Organization-RateLimit-Limit: 60;w=60;b=60
RateLimit-Remaining: 50
RateLimit-Reset: 30
Interpretation of response header values
Response Header | Description |
Organization-RateLimit-Limit | 60;w=60;b=60 |
RateLimit-Remaining | The value of this response header indicates the number of remaining API calls that you can make within that particular 48 seconds. This value continuously gets updated after every API call you make and is refreshed after the end of every 48 seconds. |
RateLimit-Reset | The value of this response header indicates the time in seconds for the next refill of API calls. If the value is 30, it means that the rate limit will be refreshed to the maximum value of 60 after 30 seconds. |
Use Case 2: when both organization (account)-level and API-level limits are defined
Consider a scenario where the organization (account)-level limit and API-level have been defined as follows:
5000 organization calls per day; Refill rate is 200 calls per hour; bucket capacity is 400.
400 API calls per hour for any particular API (such as the API to retrieve the list of centers); Refill rate is 50 calls every 10 minutes; bucket capacity is 150.
The bucket capacity is always given first preference. In other words, initially 150 API calls to retrieve the list of centers are available for the first 10 minutes and 400 organization calls during the first hour.
Let us assume that you have consumed 1000 organization credits during the first 14 hours. And in the current hour window, you have consumed 300 API credits in 40 minutes.
In such a scenario, the closest limit that could reach first is the API-level. Consequently, the server displays the respective RateLimit -* headers to indicate the following:
50 API-level calls are remaining
Next refill of 50 calls will occur in 600 sec (10 min)
Response
HTTP/1.1 200 Ok
Content-Type: application/json
API-RateLimit-Limit: 50;w=600;b=150
Organization-RateLimit-Limit: 200;w=3600;b=400
RateLimit-Limit: 50;w=600;b=150
RateLimit-Remaining: 50
RateLimit-Reset: 600
Interpretation of response header values
Response Header | Description |
API-RateLimit-Limit | 50;w=600;b=150 This indicates that the refill rate is 50 calls per 600 seconds (where, w=60 sec). After every 10 minutes, 50 calls will be added to the bucket. b=150 indicates that the maximum number of calls that can get accumulated over time is 150. In other words, even if you do not make any API call for 30 minutes, a maximum of 150 calls will get accumulated. No more call accumulation can occur beyond this value, because 150 is the maximum capacity of the bucket. |
Organization-RateLimit-Limit | 200;w=3600;b=400 |
RateLimit-Limit | 50;w=600;b=150 This header indicates the policy that could expire first: whether organization-level or API-level. In the previously mentioned response, this header displays the values corresponding to the API-level policy. |
RateLimit-Remaining | The value of this response header indicates the number of remaining API calls that you can make within that particular 50 seconds. This value continuously gets updated after every API call you make and is refreshed after the end of every 50 seconds. |
RateLimit-Reset | The value of this response header indicates the time in seconds for the next refill of API calls. If the value is 600, it means that 50 more requests will be added to the existing remaining limit, which can max up to 150. |
Use Case 3: when organization (account)-level or API-level limit exceeds and the request gets throttled
Consider a scenario where the organization (account)-level limit has been defined as follows:
Organization (account)-level quota is 60 calls per minute with a bucket capacity of 60.
In that scenario, if at any time the allowed limit is exceeded, the request will get throttled and you will receive this response: Http 429 Too Many Requests.
The server will also display the appropriate value for the Retry-After header.
Response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 39.44
Body (when the organization (account)-level quota has been exceeded)
{
"code": 429,
"message": "Account quota exceeded!"
}
Body (when the API-level quota has been exceeded)
{
"code": 429,
"message": "API quota exceeded!"
}
Interpretation of response header
The Retry-After header displays the time in seconds that you must wait before making another request, because you have exceeded the allowed limits. After that specified time, the next refill will occur; post which, further requests can be served.
In the response mentioned earlier, you must wait for about 39.44 seconds. After the completion of those 39.44 seconds, refill of 60 calls will occur. In other words, after 39.44 seconds, your organization can again make 60 calls in the next 60 seconds.
See Also