Rate limits
OwlViz applies fixed-window rate limits when Redis is configured. Limits depend on whether the request is **anonymous** or **keyed** (Authorization: Bearer ov_live_…).
Plan defaults (60s window)
| plan_id | Global RPM | Expensive RPM |
|---|---|---|
free | 120 | 60 |
builder | 600 | 300 |
pro | 2000 | 1000 |
Anonymous traffic uses Free-tier IP buckets. Keyed traffic uses your account plan_id.
Headers
Successful responses may include:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Window limit |
X-RateLimit-Remaining | Remaining requests in window |
X-RateLimit-Reset | Unix timestamp when the window resets |
When limited, the API returns **429** with Retry-After (seconds).
Expensive routes
Per-route counters apply to heavy endpoints (asset resolve, inspection, collection market refresh paths). See the full route list in [errors-and-rate-limits.md](./errors-and-rate-limits.md#tiers).
SDK / fetch retries
The SDK does not auto-retry 429. Back off using Retry-After or exponential delay with jitter. Example: [docs/api/examples/08-rate-limit-retry.ts](./examples/08-rate-limit-retry.ts).
Metering note
Keyed successful requests also increment daily Postgres usage counters (C2.5) for portal visibility — not billing in this sprint.