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 Code	HTTP Status	Description	Solution
42901	429	Too many OAuth tokens	Reuse existing token
42910	429	Monthly limit exceeded	Wait 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;
        }
    }
}