Skip to main content

API v3 Rate Limiting

Overview​

The Bookingkit API v3 implements multiple layers of rate limiting to ensure fair usage and system stability. Understanding these limits is crucial for building reliable integrations.

Rate Limiting Layers​

1. OAuth Token Rate Limiting​

Soft Limit: One active token per client per hour

How It Works​

  • Each client can have only one active OAuth token at a time
  • Tokens expire after 1 hour (3600 seconds)
  • Attempting to create a new token while one is active results in error code 42901 with 429 http error

Error Response​

{
"error_code": 42901,
"error": "Too many requests",
"error_description": "please reuse your oauth tokens"
}

2. Monthly Request Rate Limiting​

Default Limit: 500,000 requests monthly per vendor or marketplace client

How It Works​

  • Monthly limits are tracked per API client.
  • All methods (GET/POST/PATCH/DELETE) are counted.
  • Requests against the token endpoint are not counted. Getting tokens does not affect the monthly rate limit. The tokens are limited only by the token rate limit.
  • Only requests from marketplace clients and vendor clients clients are counted.
  • We do not count requests from:
    • reach application,
    • bookingkit apps,
    • mobile applications.
  • If a vendor has multiple OAuth clients the limit will still count across all the OAuth clients.
  • The count and locks are reset on the 1 day of every month

A quick way to check if a request will be tracked is to check the public_use property of the token that is bein used, only requests for public use (public_use = 1) are being tracked

Client-Specific Limits​

The default limit can be modified. Please contact support if you need a higher limit.

Error Response​

{
"error_code": 42910,
"error": "Too many requests",
"error_description": "You exceeded your monthly request limit. Your current limit is 500000 requests per month"
}

3. Request Monitoring​

Rate Limit Notifications​

Email Notifications​

The system sends email notifications at specific usage thresholds:

50% Usage Warning​

  • Triggered when usage reaches 50% of monthly limit
  • Sent once per month per client

80% Usage Warning​

  • Triggered when usage reaches 80% of monthly limit
  • Sent once per month per client

90% Usage Warning​

  • Triggered when usage reaches 90% of monthly limit
  • Sent once per month per client

100% Usage Limit​

  • Triggered when usage reaches 100% of monthly limit
  • Blocks all further requests until next month
  • Sends notification email

Error Handling​

Rate Limit Error Codes​

Error CodeHTTP StatusDescriptionSolution
42901429Too many OAuth tokensReuse existing token
42910429Monthly limit exceededWait for next month or contact support

Best Practices​

1. Token Management​

  • Cache Tokens: Store tokens for the full hour duration
  • Reuse Tokens: Don't request new tokens unnecessarily
  • Handle Expiry: Implement proper token refresh logic
  • Error Recovery: Handle 42901 errors gracefully

2. Request Optimization​

  • Batch Requests: Combine multiple requests when possible
  • Use Pagination: Implement proper pagination for large datasets
  • Cache Responses: Cache frequently accessed data
  • Use webhooks: Get updates from bookingkit by implementing webhooks
  • Delta requests: Retrieve only the modified data by using delta_since query parameter
  • Monitor Usage: Track your API usage to avoid limits

3. Error Handling​

  • Implement Retry Logic: Handle rate limit errors with exponential backoff
  • Monitor Notifications: Watch for email notifications about usage
  • Plan Ahead: Monitor usage to avoid hitting limits unexpectedly

4. Development Practices​

  • Test with Limits: Test your application with rate limiting in mind
  • Implement Queues: Use background jobs for non-critical requests
  • Monitor Metrics: Track request patterns and optimize accordingly

Implementation Examples​

PHP - Token Management​

<?php
class BookingkitAPI {
private $accessToken;
private $tokenExpiry;

public function getAccessToken() {
// Check if we have a valid cached token
if ($this->accessToken && $this->tokenExpiry > time()) {
return $this->accessToken;
}

try {
$response = $this->requestToken();
$this->accessToken = $response['access_token'];
$this->tokenExpiry = time() + $response['expires_in'];

return $this->accessToken;
} catch (Exception $e) {
if ($e->getCode() === 42901) {
// Token rate limit - wait and retry
sleep(60);
return $this->getAccessToken();
}
throw $e;
}
}

public function makeRequest($endpoint, $method = 'GET', $data = null) {
try {
$response = $this->executeRequest($endpoint, $method, $data);
return $response;
} catch (Exception $e) {
if ($e->getCode() === 42910) {
// Monthly limit exceeded
throw new Exception('Monthly API limit exceeded. Please contact support or wait until next month.');
}
throw $e;
}
}
}

JavaScript - Rate Limit Handling​

class BookingkitAPI {
constructor(clientId, clientSecret) {
this.clientId = clientId;
this.clientSecret = clientSecret;
this.accessToken = null;
this.tokenExpiry = 0;
}

async getAccessToken() {
// Check if we have a valid cached token
if (this.accessToken && this.tokenExpiry > Date.now()) {
return this.accessToken;
}

try {
const response = await this.requestToken();
this.accessToken = response.access_token;
this.tokenExpiry = Date.now() + (response.expires_in * 1000);

return this.accessToken;
} catch (error) {
if (error.error_code === 42901) {
// Token rate limit - wait and retry
await new Promise(resolve => setTimeout(resolve, 60000));
return this.getAccessToken();
}
throw error;
}
}

async makeRequest(endpoint, method = 'GET', data = null) {
try {
const response = await this.executeRequest(endpoint, method, data);
return response;
} catch (error) {
if (error.error_code === 42910) {
throw new Error('Monthly API limit exceeded. Please contact support or wait until next month.');
}
throw error;
}
}
}
Last updated: October 12, 2026 at 12:38 PM UTC