API Rate Limits
Zenoti uses rate limits to ensure faster API response times and to maintain overall stability. If we receive a large quantity of API call requests within a small period, those requests may be throttled.
Rate Limit Response Headers
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. NoteGenerally, 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 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.
Reasons for imposing rate limits
Zenoti imposes API rate limits to prevent our servers from overloading and to maintain a high quality of service. Rate limits enable a wider range of users to make API request calls by ensuring specific users or regions do not dominate concurrent connections to a server. This allows a larger number of users with more diverse needs to connect to a wider collection of servers, thereby increasing the user base support.
Strategies to effectively manage
To avoid reaching your rate limits, you must make only the essential requests that you require.
Here are a few strategies that can help you to reduce the number of requests and avoid getting rate limit exception responses:
Eliminate unnecessary API calls.
Are some of your requests receiving data items that are not used in your application? You can optimize your code to only fetch the data that your app requires.
Cache frequently used data.
You can cache data on the server or on the client by using DOM storage. You can also save relatively static information in a database or serialize it in a file.
For example, you can cache the list of services, therapists performing the services, and their pricing details for a service booking workflow.
Use Retry Logic.
You can implement Retry logic after a certain amount of time if you receive an API rate limit exception as a response.
For instance, Zenoti recommends that you verify the API responses after each API call you make. If you get an API rate limit exception, you must implement the Sleep option for some time and then try again.
You should include code that catches errors. If you ignore such API rate limit exception errors and continue to make requests, your app will not be able to recover in a graceful manner.
You can use the Retry-After header if you receive a 429 response for the back-off time. Alternatively, you can use metadata (included with all API responses) for your app’s API usage to dynamically control the app’s behavior.
Queue API requests.
To queue your API requests for effectively managing API rate limits, use any one of several cloud applications that are available in the market. Here are a few such cloud applications that you can try out:
Avail higher rate limits
The standard applicable rate limit is 60 calls per minute. To opt for a higher-volume API rate limit, reach out to your Zenoti account manager and the relevant team will share the available add-on options with you.