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

# Rate Limits

> LENS API rate limits — sliding-window counters at both the IP and API-key level. Per-minute and per-month quotas, with response headers for proactive throttling.

The API enforces rate limits at two levels: **per IP address** (all requests) and **per API key** (authenticated requests). Both use a sliding-window counter backed by Redis.

## IP-based rate limiting

Every request is rate-limited by source IP, regardless of authentication.

| Scope      | Limit           |
| ---------- | --------------- |
| Per minute | 600 requests    |
| Per day    | 15,000 requests |

These limits apply per IP address. If multiple API keys share the same IP (e.g. corporate NAT), they share this budget.

## API key rate limiting

Authenticated requests are additionally rate-limited per API key. These limits are configured per key and depend on your plan.

| Scope      | Default        | Description                                     |
| ---------- | -------------- | ----------------------------------------------- |
| Per minute | 60 requests    | Sliding 60-second window                        |
| Per month  | 3,000 requests | Resets monthly                                  |
| Unique IPs | 20             | Maximum distinct IP addresses per key per month |

Your actual limits may differ from the defaults above depending on your plan.

## Response headers

Every response includes rate-limit headers so you can track your usage:

| Header                         | Description                              |
| ------------------------------ | ---------------------------------------- |
| `X-RateLimit-Limit`            | Total requests allowed for the period    |
| `X-RateLimit-Remaining`        | Requests remaining in the period         |
| `X-RateLimit-Reset`            | Seconds until the period counter resets  |
| `X-RateLimit-Limit-Minute`     | Requests allowed per minute              |
| `X-RateLimit-Remaining-Minute` | Requests remaining in the current minute |
| `X-RateLimit-Limit-IP`         | Maximum unique IPs allowed for the key   |
| `X-RateLimit-Remaining-IP`     | Unique IPs remaining                     |

## Error responses

When a rate limit is exceeded, the API returns `429 Too Many Requests` with a JSON body:

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests per minute. Check X-RateLimit-Limit-Minute and X-RateLimit-Remaining-Minute headers.",
  "retry_after_seconds": 60
}
```

The `Retry-After` header is also set, indicating how many seconds to wait before retrying.

### Possible rate-limit errors

| Cause                     | Message hint                                    | Retry after                |
| ------------------------- | ----------------------------------------------- | -------------------------- |
| Per-minute limit exceeded | `Too many requests per minute`                  | 60 seconds                 |
| Monthly limit exceeded    | `Monthly request limit exceeded`                | Seconds until period reset |
| Too many unique IPs       | `Too many requests from different IP addresses` | Seconds until period reset |

## Best practices

Monitor `X-RateLimit-Remaining` and `X-RateLimit-Remaining-Minute` headers to proactively throttle before hitting limits.

* **Use exponential backoff** — when you receive a `429`, wait for the `Retry-After` duration before retrying.
* **Consolidate IPs** — if you run distributed workers, be aware of the unique IP limit per key.
* **Use POST multi-search** — combine multiple queries into a single request where possible.