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

# Rate Limits

> How Oculus rate limiting works, what to do when you hit a limit, and how to configure it for your infrastructure.

Oculus enforces rate limits to protect the platform from abuse and ensure fair usage across tenants.

## How it works

Rate limiting uses an **IP-based sliding window** counter stored in Redis. Each request increments a counter keyed by client IP. When the counter exceeds the configured limit within the window, the request is rejected with HTTP `429 Too Many Requests`.

Per-tenant plan limits are also enforced. The effective limit for a request is the lower of the global IP limit and the tenant's plan limit:

| Plan       | Requests per minute |
| ---------- | ------------------- |
| Starter    | 100                 |
| Pro        | 1,000               |
| Enterprise | Unlimited           |

## The `Retry-After` header

Every `429` response includes a `Retry-After` header indicating how many seconds to wait before retrying:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 12
```

The Oculus frontend SDK reads this header and surfaces a toast: `"Rate limit reached — try again in 12s"`.

## Redis fail-open behaviour

Rate limiting depends on Redis. If Redis is unavailable, rate limiting **fails open** — requests are allowed through without being counted. This is a deliberate availability trade-off. If you require strict enforcement, ensure Redis is highly available (see [Security Architecture](/concepts/security-architecture)).

## Configuring `TRUSTED_PROXY_COUNT`

Oculus extracts the real client IP from the `X-Forwarded-For` header. The `TRUSTED_PROXY_COUNT` setting tells the app how many trusted reverse-proxy hops sit in front of it, preventing IP spoofing via a crafted `X-Forwarded-For` header.

Set it to match your infrastructure:

| Setup                     | `TRUSTED_PROXY_COUNT` |
| ------------------------- | --------------------- |
| Direct (no proxy)         | `0`                   |
| Single load balancer      | `1` (default)         |
| CDN + load balancer       | `2`                   |
| CDN + WAF + load balancer | `3`                   |

```bash theme={null}
# .env
TRUSTED_PROXY_COUNT=1
```

If set too low, the app may rate-limit your load balancer's IP instead of the real client. If set too high, clients can spoof their IP by prepending values to `X-Forwarded-For`.

## Increasing your limit

Contact [support@antiailabs.com](mailto:support@antiailabs.com) or upgrade your plan to increase your rate limit.