Rate limits
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:
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.