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

# Chevre API Rate Limits, Headers, and Backoff Strategies

> Understand Chevre's per-key rate limit tiers, response headers, 429 handling, and best practices for building resilient API integrations.

Chevre enforces rate limits to ensure fair usage and platform stability. Rate limits are applied per API key per minute, so each key you create has its own independent quota — spreading load across multiple keys gives you additional headroom when needed.

## Rate Limit Tiers

Your plan determines the number of requests your key can make per minute. Burst allowance lets you briefly exceed the per-minute limit to absorb short traffic spikes.

| Plan       | Requests / minute | Burst allowance |
| ---------- | ----------------- | --------------- |
| Free       | 100               | 120             |
| Pro        | 1,000             | 1,200           |
| Enterprise | Custom            | Custom          |

## Rate Limit Response Headers

Every API response includes the following headers so you can monitor your consumption in real time and throttle proactively:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1716825600
```

| Header                  | Description                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | The maximum number of requests allowed per minute for your API key.                                   |
| `X-RateLimit-Remaining` | The number of requests remaining in the current one-minute window.                                    |
| `X-RateLimit-Reset`     | A Unix timestamp indicating when the current window resets and the counter returns to the full limit. |

## Handling a 429 Response

When you exceed your rate limit, Chevre returns a `429 Too Many Requests` response. The response includes a `Retry-After` header indicating how many seconds to wait before retrying, and the body provides the same value in the `retry_after` field.

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 23 seconds.",
    "status": 429,
    "retry_after": 23
  }
}
```

## Best Practices

Follow these practices to build integrations that stay well within limits and recover gracefully when they don't:

* **Monitor `X-RateLimit-Remaining` proactively.** When the remaining count drops below a threshold that matters for your workload, introduce a small delay before the next request rather than waiting for a 429.
* **Implement exponential backoff on 429 responses.** Don't retry immediately — wait for the `Retry-After` duration, and increase the wait time with each successive failure.
* **Cache responses where possible.** If multiple parts of your application need the same data, fetch it once and share the cached result rather than making redundant API calls.
* **Use bulk endpoints when available.** Several Chevre endpoints accept arrays of resources in a single request. Batching operations reduces the total number of requests you make.

## Exponential Backoff Example

The following example retries a failed request with exponential backoff, reading the `Retry-After` header to respect the server-specified wait time before applying the multiplier:

```javascript exponential-backoff.js theme={null}
async function fetchWithBackoff(url, options, retries = 5) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;
    const retryAfter = parseInt(res.headers.get('Retry-After') || '1', 10);
    await new Promise(r => setTimeout(r, retryAfter * 1000 * Math.pow(2, i)));
  }
  throw new Error('Max retries exceeded');
}
```

<Note>
  Enterprise customers can request a custom rate limit increase to accommodate high-volume workloads. Reach out to [support@chevre.io](mailto:support@chevre.io) with your use case and expected request volume.
</Note>