Rate Limits

The API implements rate limiting to ensure fair usage and system stability:

Daily Limit

50

Requests per day per API key

Second Limit

1

Request per second per API key

Rate Limit Headers

Every API response includes headers with current rate limit information:

Header	Description	Example
X-RateLimit-Limit	Maximum requests allowed in the current window	`50`
X-RateLimit-Remaining	Number of requests remaining in the current window	`42`
X-RateLimit-Reset	UTC time when the rate limit window resets	`1642608000`
Retry-After	Seconds to wait before making another request (only when limit exceeded)	`3600`

Handling Rate Limit Exceeded

When you exceed the rate limit, the API returns HTTP status 429 Too Many Requests:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642608000
Retry-After: 3600

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit. Please try again later.",
  "timestamp": "2024-01-15T09:30:00+00:00"
}

Best Practices

Implement Exponential Backoff

When receiving a 429 response, wait progressively longer before retrying:

function makeApiRequest(url, options, retries = 0) {
    return fetch(url, options)
        .then(response => {
            if (response.status === 429) {
                const retryAfter = response.headers.get('Retry-After');
                const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, retries) * 1000;
                
                return new Promise(resolve => {
                    setTimeout(() => {
                        resolve(makeApiRequest(url, options, retries + 1));
                    }, delay);
                });
            }
            return response;
        });
}

Monitor Rate Limit Headers

Check rate limit headers in every response to avoid hitting limits:

const response = await fetch(apiUrl, options);
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

if (remaining < 5) {
    console.warn('Approaching rate limit. Remaining:', remaining);
    // Consider slowing down requests
}

Cache Responses

Cache API responses when possible to reduce the number of requests:

Cache client data that doesn't change frequently
Use conditional requests with If-Modified-Since headers
Implement local storage for reference data

Batch Requests

Use pagination parameters effectively to get more data in fewer requests:

// Instead of multiple small requests
GET /api/client.fetchAll?per_page=10&page=1
GET /api/client.fetchAll?per_page=10&page=2
GET /api/client.fetchAll?per_page=10&page=3

// Use larger page sizes when possible
GET /api/client.fetchAll?per_page=100&page=1

Rate Limit Increases

If your application requires higher rate limits, please contact your system administrator. When requesting an increase, please include:

Your current API key
Expected request volume
Use case description
Business justification

Enterprise Users: Higher rate limits are available for enterprise accounts. Contact support for custom rate limit configurations.

Rate Limiting