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

# API Rate Limits, Request Budgets, and Backoff — Fliqr AI

> Understand how Fliqr AI enforces per-key request budgets, read rate limit headers, and handle 429 responses without dropping data.

Fliqr AI enforces rate limits on every API key to protect platform stability and ensure consistent performance for all users. When your application exceeds its request budget, the API returns a `429 Too Many Requests` response. Design your integration to read the rate limit headers on every response and back off before the limit is reached — not after.

## Request Limits

Each API key has the following budget:

| Window                    | Limit                       |
| ------------------------- | --------------------------- |
| Rolling 60-second window  | **100 requests per minute** |
| Burst window (10 seconds) | **200 requests**            |

The per-minute limit applies on a rolling basis, not a fixed clock boundary. The burst limit allows short spikes in traffic but prevents sustained overload. Both limits are enforced independently — exceeding either triggers a `429`.

## Rate Limit Headers

Every API response includes three headers that report your current usage:

| Header                  | Type    | Description                                    |
| ----------------------- | ------- | ---------------------------------------------- |
| `X-RateLimit-Limit`     | integer | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | integer | Requests remaining before you hit the limit    |
| `X-RateLimit-Reset`     | integer | Unix timestamp (UTC) when the window resets    |

**Example response headers:**

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705312200
```

<Tip>
  Check `X-RateLimit-Remaining` proactively on every response. If it falls below **10**, pause your client and wait until the timestamp in `X-RateLimit-Reset` before sending further requests.
</Tip>

## 429 Response

When you exceed the rate limit, the API returns:

**HTTP 429 Too Many Requests**

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 2025-01-15T10:30:00Z.",
    "retry_after": "2025-01-15T10:30:00Z"
  }
}
```

The response also includes a `Retry-After` header with the number of seconds to wait before retrying. Honor this value — retrying immediately will continue to return `429` and consume your quota for the burst window.

## Handling 429 in Code

Implement exponential backoff with a maximum retry count. The following JavaScript example reads the `Retry-After` header and waits accordingly:

```javascript rate-limit-handler.js theme={null}
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;
    const retryAfter = res.headers.get('Retry-After') || 60;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  }
  throw new Error('Rate limit retries exhausted');
}
```

For batch operations — such as tagging thousands of contacts — introduce deliberate delays between requests rather than firing them in parallel. A simple approach is to throttle to 80 requests per minute (leaving a 20% safety margin) using a request queue.

## Best Practices

* **Read headers, don't guess.** Always inspect `X-RateLimit-Remaining` rather than assuming your request count is safe.
* **Use bulk endpoints.** Where available, prefer endpoints that accept arrays of resources over looping individual calls.
* **Queue background jobs.** For high-volume operations, use a task queue with a rate-limited worker rather than making synchronous API calls from a user-facing request path.
* **Avoid concurrent bursts.** Fan-out patterns that fire many parallel requests simultaneously are the most common cause of hitting the burst limit.

***

## What's Next

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/api-reference/authentication">
    Set up API key authentication and learn key rotation best practices.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/docs/api-reference/errors">
    See the full error code reference, including how to handle 500-level server errors with backoff.
  </Card>
</CardGroup>