# Rate Limits

> Tradavity Public API rate limits: per-key, per-user, per-day, with X-RateLimit headers and Retry-After semantics.
> Source: https://help.tradavity.com/api-docs/rate-limits
> Category: Core Concepts

---

Limits are enforced two ways: **per-key** and **per-user**. The tighter window wins. Rate-limit info is on every successful response in `meta.rate_limit` and as headers:

> **60-second sliding window**
> The limit counts requests made in the last 60 seconds, not requests since a fixed reset point. The bucket refills *gradually* as old requests age out, not all at once. On `429`, `Retry-After` tells you when the **oldest request** in your window ages out — i.e. when **one** slot frees up, not when the full limit refills. After sleeping `Retry-After` seconds you can make roughly one more call before backing off again; the bucket recovers to full only after no requests have been made for a full minute.

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Max requests per minute for this key’s tier |
| `X-RateLimit-Remaining` | Remaining requests in the current 60-second window |
| `X-RateLimit-Reset` | Unix timestamp at which the current rolling window’s newest entry will age out (sliding-window upper bound) |
| `X-RateLimit-Scope` | On 429 responses: `key`, `user`, or `key-daily` |
| `Retry-After` | On 429 responses: seconds until **one** slot frees in the rolling window (not until the full limit refills) |

Tier limits:

| Tier | Per key / minute | Per key / day | Per user / minute (across all keys) |
| --- | --- | --- | --- |
| Free | 60 | 5,000 | 180 |
| Pro | 300 | 50,000 | 900 |

The per-user ceiling is roughly 3× the per-key ceiling so up to three keys on one account can all run full-throttle simultaneously without hitting the cross-key limit. Once you have more than three active keys, the per-user window becomes the binding constraint.

There is also a pre-auth IP rate limit of **100 requests / minute** for unauthenticated traffic, returning `429 rate_limited` with `X-RateLimit-Scope: ip-preauth`. This blocks key-stuffing scanners before they hit the auth lookup.

When you exceed a limit you get HTTP `429` with error code `rate_limited`. Sleep for `Retry-After` seconds and try again. Authenticated requests count against the limit whether they succeed or fail (so 4xx responses still tick the counter). Pre-auth 401s on totally invalid keys are not counted per-key (no key id is known yet); they are still logged for abuse forensics.