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 HTTP429 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:
"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).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 |
X-Forwarded-For.