API Rate Limits

SeroBook applies rate limits to API requests to ensure fair usage, protect platform stability, and maintain fast response times for all users. This guide explains how rate limits work, what your limits are, and how to build resilient integrations that handle rate limiting gracefully.

Rate Limiting Overview

Rate limiting controls how many API requests your application can make within a given time window. Every API request you make counts toward your limit, and once you reach the limit, additional requests are temporarily rejected until the window resets.

SeroBook uses a sliding window algorithm for rate limiting. Unlike fixed windows that reset at specific clock times, a sliding window considers your request pattern over a rolling period. This means you get a more consistent experience without sudden bursts of allowed requests followed by hard blocks.

What Counts as a Request

• Every API call to any /api/v1/ endpoint counts as one request
• Both successful (2xx) and failed (4xx) responses count toward your limit
• Requests that are rate-limited (429 status) do not count toward your limit
• Webhook deliveries from SeroBook to your endpoints do not count
• Dashboard activity by your team does not consume your API rate limit

Rate Limits by Plan

Your API rate limits depend on your SeroBook subscription plan. Here are the limits for each plan:

Free Plan

• Read requests: 60 per minute
• Write requests: 30 per minute
• Daily cap: 1,000 total requests per day
• Burst allowance: None

Starter Plan

• Read requests: 300 per minute
• Write requests: 100 per minute
• Daily cap: 10,000 total requests per day
• Burst allowance: Up to 500 requests in a 10-second window

Pro Plan

• Read requests: 1,000 per minute
• Write requests: 300 per minute
• Daily cap: 100,000 total requests per day
• Burst allowance: Up to 2,000 requests in a 10-second window

Enterprise

• Read requests: Custom (default 5,000 per minute)
• Write requests: Custom (default 1,000 per minute)
• Daily cap: Custom (default unlimited)
• Burst allowance: Custom

Rate Limit Headers

Every API response includes headers that tell you your current rate limit status. Use these headers to monitor your usage and avoid hitting limits:

Response Headers

• X-RateLimit-Limit – The maximum number of requests allowed in the current time window. Example: X-RateLimit-Limit: 300
• X-RateLimit-Remaining – The number of requests remaining in the current window. Example: X-RateLimit-Remaining: 247
• X-RateLimit-Reset – The Unix timestamp (in seconds) when the current window resets. Example: X-RateLimit-Reset: 1706500000
• X-RateLimit-Type – Whether this limit applies to "read" or "write" operations. Example: X-RateLimit-Type: read

Reading the Headers

Check these headers after every request to understand your current position relative to the limit. When X-RateLimit-Remaining approaches zero, slow down your requests or pause until the reset time.

Here's an example of parsing rate limit headers in JavaScript:

const response = await fetch('https://api.serobook.com/api/v1/bookings', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));

if (remaining < 10) {
  const waitMs = (resetTime * 1000) - Date.now();
  console.log('Approaching rate limit, waiting ' + waitMs + 'ms');
  await new Promise(resolve => setTimeout(resolve, waitMs));
}

Handling Rate Limit Errors

When you exceed your rate limit, the API returns an HTTP 429 Too Many Requests response. Your integration should handle this gracefully.

The 429 Response

A rate-limited response looks like this:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706500030

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded the rate limit. Please retry after 30 seconds.",
  "retry_after": 30
}

Implementing Retry Logic

The recommended approach for handling 429 responses is exponential backoff with jitter:

1. Catch the 429 response
2. Read the Retry-After header to determine the minimum wait time
3. Wait at least that long before retrying
4. If the retry also fails, double the wait time (exponential backoff)
5. Add a small random delay (jitter) to prevent all retries from hitting the API simultaneously
6. Set a maximum number of retries (e.g., 5) to prevent infinite loops

Best Practices

Follow these best practices to use the SeroBook API efficiently and avoid rate limit issues:

Optimize Request Volume

• Use pagination wisely – Request larger page sizes (up to 100 records per page) to reduce the number of requests needed to fetch data
• Cache responses – Store API responses locally and only re-fetch when data changes. Use the If-Modified-Since header for conditional requests that don't count toward your limit if the data hasn't changed
• Use webhooks for real-time updates – Instead of polling the API for changes, configure webhooks to receive push notifications when bookings, customers, or payments change
• Batch operations where possible – Some endpoints support batch operations (e.g., updating multiple bookings in a single request). Use these to reduce your request count

Design Resilient Integrations

• Monitor rate limit headers – Check X-RateLimit-Remaining after every request and proactively slow down before hitting the limit
• Implement exponential backoff – Always use backoff with jitter for retrying failed requests
• Queue non-urgent requests – For background sync operations, spread requests over time rather than sending them all at once
• Set request timeouts – Use reasonable timeouts (30 seconds) to prevent hanging requests from consuming resources
• Log rate limit events – Track when your integration hits rate limits so you can identify patterns and optimize

Avoid Common Mistakes

• Don't poll in tight loops – Avoid polling the API every second. Use webhooks or poll at reasonable intervals (e.g., every 30 seconds or longer)
• Don't ignore 429 responses – Some clients treat 429 as a generic error and retry immediately, making the problem worse
• Don't use multiple API keys to bypass limits – Rate limits are enforced per account, not per API key. Using multiple keys will not increase your limit

Requesting Limit Increases

If your integration legitimately requires higher rate limits than your current plan provides, you have several options:

Upgrade Your Plan

The simplest way to increase your limits is to upgrade to a higher plan. Each plan tier provides significantly higher limits. You can upgrade instantly from Settings > Billing > Change Plan.

Request a Custom Increase

For Pro plan customers who need limits beyond the standard allocation, you can request a custom increase:

1. Contact support at api-support@serobook.com
2. Include the following in your request:
   • Your account ID and current plan
   • The specific limits you need (read/write per minute, daily cap)
   • A description of your use case and why the standard limits are insufficient
   • Your expected request patterns (e.g., steady stream vs. periodic bursts)
3. Our team will review your request within 2 business days
4. If approved, the new limits are applied to your account and you'll receive confirmation by email

Monitoring API Usage

Track your API consumption to stay informed and avoid unexpected rate limiting:

API Usage Dashboard

View your API usage at Settings > API > Usage. The dashboard shows:

• Requests today – Total API requests made in the current 24-hour period vs. your daily cap
• Requests this minute – Current per-minute usage shown in real-time
• Historical chart – A line chart of daily API usage over the past 30 days
• Top endpoints – Which endpoints receive the most requests, helping you identify optimization opportunities
• Error rate – Percentage of requests returning errors, including 429 rate limit errors

Usage Alerts

Set up alerts to be notified when you're approaching your limits:

1. Navigate to Settings > API > Alerts
2. Click New Alert
3. Choose the threshold (e.g., "75% of daily cap" or "90% of per-minute limit")
4. Select the notification method: email, webhook, or both
5. Save the alert

API Logs

Detailed request logs are available at Settings > API > Logs for the past 7 days. Each log entry shows the endpoint called, HTTP method, response status code, response time, and timestamp. Use these logs to debug issues and optimize your integration.

Frequently Asked Questions

Do rate limits apply to Zapier integrations?

Yes. Zapier actions use your API quota. Each Zap trigger check or action counts as one API request. If you have many active Zaps, monitor your usage to ensure you stay within limits.

What happens to webhooks if I'm rate-limited?

Incoming webhooks from SeroBook to your endpoints are not affected by rate limits. Rate limits only apply to requests you make to the SeroBook API. However, if your Zap or integration makes API calls in response to a webhook, those calls count toward your limit.

Can I see which requests are consuming my quota?

Yes. The API logs under Settings > API > Logs show every request made against your API key, including the endpoint, method, and timestamp. The top endpoints view on the usage dashboard summarizes your heaviest consumers.

Do rate limits reset at midnight?

Per-minute limits use a sliding window and reset continuously. Daily caps reset at midnight UTC. The X-RateLimit-Reset header always tells you when the current per-minute window will reset.

Next Steps

Now that you understand API rate limits:

• Review the platform security overview
• Set up API key permissions and access controls
• Learn about exporting data via the API