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

# Rate Limiting

> API rate limit policies and handling

IllumiChat applies rate limits to protect platform stability and ensure fair usage.

## Rate Limit Tiers

| Tier                        | Limit                           | Scope          |
| --------------------------- | ------------------------------- | -------------- |
| **Authenticated endpoints** | Generous limits per user        | Per user       |
| **Widget public endpoints** | 5 requests per minute           | Per IP address |
| **File downloads**          | 20 requests per minute          | Per user       |
| **SMS webhooks**            | Governed by Twilio sending rate | Per assistant  |

<Note>
  Authenticated endpoint limits are designed to support normal application usage. If you are building a high-throughput integration, see the guidance below on requesting increased limits.
</Note>

## Widget Quotas

Widget usage is tracked per assistant and subject to quota limits based on your subscription plan.

| Detail          | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| **Tracking**    | Message count is tracked per assistant                      |
| **Reset cycle** | Quotas reset periodically                                   |
| **Plan limits** | Quota thresholds depend on your workspace subscription tier |
| **Enforcement** | Requests exceeding the quota receive a `429` response       |

## Rate Limit Response

When any rate limit is exceeded, the API returns HTTP status `429`:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "rate_limit:widget"
}
```

## Handling Rate Limits

### Implement Exponential Backoff

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function fetchWithRetry(url, options, maxRetries = 5) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      const response = await fetch(url, options);
      if (response.status !== 429) return response;

      const delayMs = Math.min(1000 * Math.pow(2, attempt), 30000);
      console.warn(`Rate limited. Retrying in ${delayMs}ms...`);
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
    throw new Error("Max retries exceeded");
  }
  ```

  ```python Python theme={null}
  import time
  import requests

  def fetch_with_retry(url, headers=None, max_retries=5):
      for attempt in range(max_retries):
          response = requests.get(url, headers=headers)
          if response.status_code != 429:
              return response

          delay = min(2 ** attempt, 30)
          print(f"Rate limited. Retrying in {delay}s...")
          time.sleep(delay)

      raise Exception("Max retries exceeded")
  ```
</CodeGroup>

### Additional Strategies

* **Cache responses** that do not change frequently (e.g., assistant configurations)
* **Batch operations** where the API supports it
* **Monitor usage** to identify opportunities for optimization

## Requesting Higher Limits

If your use case requires higher rate limits, contact the IllumiChat support team with:

* Your workspace ID
* The endpoints you need higher limits for
* Your expected request volume
* A description of your integration

<Tip>
  Before requesting higher limits, review your integration for opportunities to reduce request volume through caching, batching, and efficient polling intervals.
</Tip>