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

# Rate limits

> Understand Boltcall API rate limits and how to handle them gracefully.

Boltcall enforces rate limits per API key to ensure fair usage across all customers. Limits vary by plan.

## Limits by plan

| Plan     | Rate limit              |
| -------- | ----------------------- |
| Starter  | 60 requests / minute    |
| Pro      | 300 requests / minute   |
| Ultimate | 1,000 requests / minute |

## Rate limit headers

Every API response includes the following headers so you can monitor your current usage:

| Header                  | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum number of requests allowed per minute         |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window    |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the limit window resets |

## 429 Too Many Requests

When you exceed the rate limit, the API returns a `429` status with the following body:

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Back off and retry with exponential delay.",
    "status": 429
  }
}
```

Check the `X-RateLimit-Reset` header to determine when you can resume sending requests.

## Best practices

<Tip>
  Implement exponential backoff when retrying after a 429. Start with a 1-second delay and double it on each subsequent retry, up to a maximum of 60 seconds.
</Tip>

* **Cache responses** — for read-heavy operations like listing agents or leads, cache results locally for 30–60 seconds rather than polling the API.
* **Use webhooks** — instead of polling for state changes (e.g., call completed, lead updated), subscribe to [webhook events](/api/webhooks) to receive push notifications.
* **Batch operations** — use pagination parameters (`limit`, `page`) to retrieve larger datasets in fewer requests.
* **Monitor headers** — track `X-RateLimit-Remaining` proactively and slow down before hitting zero.

### Exponential backoff example

```javascript Node.js theme={null}
async function fetchWithBackoff(url, options, maxRetries = 5) {
  let delay = 1000;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    if (attempt === maxRetries) {
      throw new Error('Rate limit exceeded — max retries reached');
    }

    await new Promise((resolve) => setTimeout(resolve, delay));
    delay = Math.min(delay * 2, 60_000);
  }
}
```