> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Understand API rate limits and how to handle throttling

## Rate Limit Overview

The Gather API implements rate limiting to ensure fair usage and system stability. Rate limits are applied per API key.

### Default Limits

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

<Callout type="info">
  Rate limits are subject to change. Contact support if you need higher limits
  for your use case.
</Callout>

## Rate Limit Headers

All API responses include rate limit information in the response 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

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "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

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    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;
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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
    ```
  </Tab>
</Tabs>

## Rate Limit Windows

Rate limits are calculated using sliding 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

Both limits must be satisfied. If either limit is exceeded, you'll receive a 429 response.

## Monitoring Your Usage

Check rate limit headers in every response to monitor your usage:

```javascript theme={null}
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

If you need higher rate limits for your use case:

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

<Callout type="info">
  Higher rate limits may be available for enterprise customers or specific use
  cases.
</Callout>

## Next Steps

<CardGroup cols={2}>
  <Card title="Error Handling" icon="alert-triangle" href="/guides/error-handling">
    Learn how to handle API errors gracefully
  </Card>

  <Card title="Best Practices" icon="check-circle" href="/guides/best-practices">
    Review best practices for API usage
  </Card>
</CardGroup>