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

# Rate Limits

> Understand API rate limiting and how to handle it

The Chariow API implements rate limiting to ensure fair usage and maintain service quality for all users.

## Default Limits

| Endpoint Type    | Limit        | Window     |
| ---------------- | ------------ | ---------- |
| All API requests | 100 requests | per minute |

Rate limits are applied per API key. Each API key has its own separate limit counter.

## Rate Limit Headers

Every API response includes headers indicating your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642089600
```

| Header                  | Description                            |
| ----------------------- | -------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the window |
| `X-RateLimit-Remaining` | Requests remaining in current window   |
| `X-RateLimit-Reset`     | Unix timestamp when the limit resets   |

## Rate Limit Exceeded

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

```json theme={null}
{
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "data": [],
  "errors": []
}
```

The response includes a `Retry-After` header indicating how long to wait:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

## Handling Rate Limits

### Exponential Backoff

Implement exponential backoff to gracefully handle rate limits:

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      const delay = Math.min(retryAfter * 1000, Math.pow(2, attempt) * 1000);

      console.log(`Rate limited. Retrying in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}
```

### Request Batching

Batch multiple operations to reduce request count:

```javascript theme={null}
// Instead of making 100 individual requests
for (const customerId of customerIds) {
  await getCustomer(customerId); // 100 requests
}

// Use pagination to get multiple at once
const customers = await listCustomers({ per_page: 100 }); // 1 request
```

### Caching

Cache responses to avoid unnecessary requests:

```javascript theme={null}
const cache = new Map();
const CACHE_TTL = 60000; // 1 minute

async function getCachedCustomer(customerId) {
  const cached = cache.get(customerId);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const response = await fetch(`/v1/customers/${customerId}`, {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const data = await response.json();
  cache.set(customerId, { data, timestamp: Date.now() });

  return data;
}
```

## Increasing Limits

If you need higher rate limits:

1. **Enterprise Plans** - Higher limits are available on enterprise plans
2. **Contact Support** - Request a temporary increase for specific use cases
3. **Optimize Usage** - Review your implementation for optimization opportunities

<Info>
  Contact [support@chariow.com](mailto:support@chariow.com) to discuss higher rate limits for your use case.
</Info>

## Best Practices

<AccordionGroup>
  <Accordion title="Monitor Your Usage" icon="chart-line">
    Track rate limit headers to understand your usage patterns and adjust accordingly.
  </Accordion>

  <Accordion title="Use Webhooks" icon="webhook">
    Instead of polling for changes, use webhooks to receive real-time notifications.
  </Accordion>

  <Accordion title="Implement Queuing" icon="list-ol">
    Queue requests and process them at a controlled rate to avoid bursts.
  </Accordion>

  <Accordion title="Cache Aggressively" icon="database">
    Cache data that doesn't change frequently to reduce API calls.
  </Accordion>
</AccordionGroup>