Rate Limiting

The Zaki-Pass API enforces rate limits to ensure fair usage and platform stability. All API responses include rate limit headers so you can monitor your usage.

Rate Limits

• 100 requests per minute per API key
• Rate limit resets every 60 seconds
• JWT-authenticated requests have separate rate limiting

Response Headers

The following headers are returned with every API response:

`X-RateLimit-Limit`	Maximum requests per window (100)
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (only present on 429 responses)

429 Response

When you exceed the rate limit, the API returns a 429 status code with the following response body:

json

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests",
  "error": "Too Many Requests"
}

Handling Rate Limits

Best practices for handling rate limits:

Implement exponential backoff
Cache responses when possible
Use batch endpoints (e.g., POST /passes/batch) instead of individual calls
Monitor your usage with the X-RateLimit-Remaining header

Retry implementation in JavaScript:

javascript

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || '5';
      const waitTime = parseInt(retryAfter, 10) * 1000;
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

Retry implementation in Python:

python

import time
import requests

def fetch_with_retry(url, headers, max_retries=3):
    for i in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 5))
            time.sleep(retry_after)
            continue

        return response
    raise Exception('Max retries exceeded')

Batch Endpoints

Use batch endpoints to reduce the number of API calls and stay within rate limits:

• POST /passes/batch — Issue multiple passes in a single request
• POST /passes/notify/batch — Send batch notifications
• Each batch call counts as a single request against the rate limit