Rate Limit Response Headers

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. This header appears only if API-level rate limit has been defined. Note: Generally, API-level rate limit is not defined for organizations. Only in case of some of the most frequently used APIs, API-level rate limit may be defined.
Organization-RateLimit-Limit	Quota of total organization-level requests (maximum limit) that can be allotted during each window. This header appears only if organization-level rate limit has been defined.
RateLimit-Limit	Quota of total requests that can be allotted during each window. This header displays the corresponding value for the level (API-level or organization-level) that could be exhausted first. This header appears only if rate limits are defined at both the organization-level and API-level.
RateLimit-Remaining	Quota of total requests that are remaining during a particular window. This header displays the corresponding remaining value for the level (API-level or organization-level) that could be exhausted first.
RateLimit-Reset	Remaining time in seconds until a particular window is reset. This header displays the corresponding remaining time for the level (API-level or organization-level) that could be exhausted first. After this time is completed, the next refill occurs for the next window.
Retry-After	Time in seconds that you must wait before making a new request. This header appears if a request gets throttled (Http 429) because the allowed rate limits have been exceeded.

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 3: when organization (account)-level or API-level limit exceeds and the request gets throttled

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 This indicates that the refill rate is 60 calls per 60 seconds (where, w=60 sec). After every 1 minute, 60 calls will be added to the bucket. b=60 indicates that the maximum number of calls that can get accumulated over time is 60. In other words, even if you do not make any API call for 2 hours, a maximum of 60 calls will get accumulated. No more call accumulation can occur beyond this value, because 60 is the maximum capacity of the bucket.
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 This indicates that the refill rate is 200 calls per 3600 seconds (where, w=3600 sec). After every 1 hour, 200 calls will be added to the bucket. b=400 indicates that the maximum number of calls that can get accumulated over time is 400. In other words, even if you do not make any API call for 2 hours, a maximum of 400 calls will get accumulated. No more call accumulation can occur beyond this value, because 400 is the maximum capacity of the bucket.
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

API Rate Limits