Rate Limits

​

Rate Limit Overview

​

Default Limits

• Per Hour: 1000 requests per hour per API key
• Burst: 100 requests per minute
• Scope: Limits are applied per API key independently

​

Rate Limit Headers

• X-RateLimit-Limit: Maximum number of requests allowed in the current window
• X-RateLimit-Remaining: Number of requests remaining in the current window
• X-RateLimit-Reset: Unix timestamp (seconds) when the rate limit window resets

​

Example Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1704067200

​

Handling Rate Limits

​

429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "resetAt": "2024-01-01T01:00:00Z"
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

​

Best Practices

1. Monitor Rate Limit Headers: Check X-RateLimit-Remaining to track your usage
2. Implement Exponential Backoff: Retry failed requests with increasing delays
3. Cache Responses: Cache frequently accessed data to reduce API calls
4. Batch Operations: Use bulk endpoints when available to reduce request count

​

Example: Exponential Backoff

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
      const waitTime = Math.max((resetTime * 1000) - Date.now(), 0);
      
      if (i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
    }
    
    return response;
  }
}

import time
import requests

def make_request_with_retry(url, headers, max_retries=3):
    for i in range(max_retries):
        response = requests.get(url, headers=headers)
        
        if response.status_code == 429:
            reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
            wait_time = max(reset_time - int(time.time()), 0)
            
            if i < max_retries - 1:
                time.sleep(wait_time)
                continue
        
        return response

​

Rate Limit Windows

• Hourly Window: 1000 requests per hour, calculated on a rolling 60-minute window
• Burst Window: 100 requests per minute, calculated on a rolling 60-second window

​

Monitoring Your Usage

const response = await fetch(
  'https://api.prod.qualifi.hr/qsi/gather/questions',
  {
    headers: { 'x-api-key': apiKey }
  }
)

const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'))
const limit = parseInt(response.headers.get('X-RateLimit-Limit'))

console.log(`Used ${limit - remaining} of ${limit} requests`)

​

Requesting Higher Limits

1. Contact support at support@qualifi.hr
2. Provide details about your expected usage patterns
3. Include your organization ID and use case description

​

Next Steps