Configure API rate limits
Zenoti enforces rate limits to ensure fair API access across all integrations. The default rate limit is 60 API calls per minute per organization. This article explains how rate limits work and strategies for staying within the limit.
Before you begin
- You need a valid API key or access token. See Set up API authentication.
Permission: Manage API Keys, Manage Apps, and Manage Automation (under Administrator) -- Required to create backend applications and generate API keys.
How rate limits work
Zenoti uses a sliding window rate limit. Each API response includes headers that tell you your current rate limit status:
| Header | Example value | Description |
|---|---|---|
| Organization-RateLimit-Limit | 60;w=60;b=60 |
60 requests per 60-second window, with a maximum burst of 60 |
| RateLimit-Remaining | 45 |
Number of API calls remaining in the current window |
| RateLimit-Reset | 30 |
Seconds until the rate limit resets |
When you exceed the rate limit, the API returns a 429 Too Many Requests response.
Steps
Monitor your rate limit usage
- Check the
RateLimit-Remainingheader in every API response to track your remaining quota. - Check the
RateLimit-Resetheader to know when the limit resets. - If
RateLimit-Remainingdrops below a threshold (for example, 10), slow down your request rate.
Implement rate limit management strategies
Use one or more of the following strategies to stay within the rate limit:
Eliminate unnecessary requests
- Batch related operations into fewer API calls where the API supports it.
- Avoid polling for data that has not changed. Use webhooks for real-time event notifications instead.
- Remove redundant or duplicate API calls from your integration logic.
Cache frequently used data
Cache data that does not change often to reduce repeated API calls:
- Server-side cache -- Store API responses in memory or a caching layer (for example, Redis) with appropriate expiration times.
- Client-side cache -- Cache responses in the browser or application for data that does not need real-time freshness.
- Database cache -- Store retrieved records in your local database and refresh them on a schedule.
Good candidates for caching include center details, service lists, employee lists, and membership plans.
Implement retry logic with exponential backoff
When you receive a 429 response, retry the request after a delay:
- Wait for the number of seconds indicated in the
RateLimit-ResetorRetry-Afterresponse header. - If no header is present, use exponential backoff: wait 1 second, then 2, then 4, then 8, up to a maximum wait time.
- Add random jitter to your retry delay to prevent multiple clients from retrying simultaneously.
Queue API requests
For high-volume integrations, implement a request queue:
- Place API requests in a queue instead of sending them immediately.
- Process the queue at a rate that stays within the 60 calls per minute limit.
- Use a message queue service (for example, Amazon SQS, ActiveMQ, or Rackspace Cloud Queues) for distributed systems.
Tips
- Design your integration to work within the 60 calls per minute limit from the start. Retroactively optimizing a rate-limited integration is more difficult.
- Use webhooks to receive push notifications for events instead of polling, which consumes rate limit quota.
- If your integration consistently needs more than 60 calls per minute, review your architecture for optimization opportunities before requesting a rate limit increase.