> For the complete documentation index, see [llms.txt](https://docs.aiclicks.io/llms.txt).
> Use it to discover all available pages before exploring further.

# Rate Limits

Per-key request quotas, response headers, and how to handle 429.


The AIclicks API rate-limits per API key on a **fixed 60-second window**. The default ceiling is **60 requests per minute per key**.

| Tier | Limit |
|---|---|
| Default | 60 requests / minute / key |
| Custom (enterprise) | Negotiated — contact [support@aiclicks.io](mailto:support@aiclicks.io). |

JWT (dashboard session) callers are not rate-limited — only `ak_` API keys are.

## Reading your current state

Every response from an API-key caller includes three rate-limit headers:

| Header | Description |
|---|---|
| `X-RateLimit-Limit` | Max requests in the window. |
| `X-RateLimit-Remaining` | Requests left in the current window. |
| `X-RateLimit-Reset` | Unix epoch seconds when the window resets. |

You can also poll [`GET /validate`](/validate) — its `data.rate_limit` field returns the same numbers in JSON:

```json
{
  "rate_limit": {
    "limit_per_minute": 60,
    "remaining": 58,
    "reset_at": 1718531412
  }
}
```

## When you hit the limit

Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{ "detail": "Too many requests. Please try again later." }
```

`Retry-After` is in seconds — wait at least that long before retrying.

## Best practices

1. **Watch `X-RateLimit-Remaining`** and slow down before hitting zero, rather than relying on `429`.
2. **Respect `Retry-After`** exactly — fixed-interval retries will hit the same wall.
3. **Cache on your side.** The server-side 1-hour cache only helps when query params match byte-for-byte. Local caching is what protects against hot loops.
4. **Stagger key usage.** If you have multiple keys, distribute traffic across them — the bucket is keyed on the API key, not the team.
5. **Use exponential backoff for 5xx**, fixed `Retry-After` for `429`. Don't conflate them.

## What counts as one request

Every HTTP call to `/api/v1/*` increments the counter, including:

- Cache hits (`X-Cache: HIT`).
- `/validate` calls.
- 4xx error responses.

5xx responses do not count — server errors are not held against the caller.