# Rate limits

200 requests per 10 seconds per key and 1,000 per minute per account, what a 429 looks like, how to back off with Retry-After, and the limits on keyless and trial endpoints.

Rate limits protect the service and your credits from runaway loops. They are generous for normal workloads, and the response tells you exactly how long to wait.

## The limits

| Scope | Limit | Applies to |
|---|---|---|
| Per API key | 200 requests per 10 seconds | Every request made with that key |
| Per account | 1,000 requests per minute | All keys of the account together |
| Keyless MCP requests | 120 per minute per IP address | Discovery tools (`search_apis`, `list_apis`, `get_api`) called without a key |
| Agent trial keys | 3 new keys per network per 24 hours, plus a daily limit across all agents | `POST /agent/signup` (an IPv6 network counts as one /64) |
| Public API request form | A small per-IP limit | `POST /v1/api-requests` |

Every authenticated request counts, including polling (`GET /v1/requests/{id}`), quotes and reads. Windows are fixed: a 10-second window starts with your first request in it and resets when it ends, rather than sliding.

## When you hit one

You get `429 Too Many Requests` with the wait in two places, the `Retry-After` header (seconds) and `retryAfterSeconds` in the body:

```http title="429 Too Many Requests"
HTTP/1.1 429 Too Many Requests
Retry-After: 4
X-Request-Id: req_01JBXW2T4V6X8Z0B2D4F6H8K0M
Content-Type: application/json

{
  "code": "rate_limited",
  "error": "Rate limit exceeded. Slow down and retry after the indicated delay.",
  "requestId": "req_01JBXW2T4V6X8Z0B2D4F6H8K0M",
  "retryAfterSeconds": 4
}
```

A `429` is never charged, and a call refused this way did not run. Wait at least `Retry-After`, then retry with the same `Idempotency-Key`. The retry helpers in [Idempotency and retries](/docs/idempotency#which-errors-to-retry) already do this.

## Staying under the limits

- **Wait longer instead of polling.** `Prefer: wait=60` keeps one request open for up to 60 seconds rather than polling every 2 seconds. See [Durable requests](/docs/durable-requests).
- **Spread bursts.** For batch jobs, cap concurrency (for example 10 to 20 calls in flight per key) instead of firing everything at once.
- **Back off with jitter** after any `429` or `5xx`, so many workers do not retry in lockstep.
- **Cache discovery.** Catalog endpoints send `Cache-Control` and `ETag` headers; reuse `GET /v1/apis/{sku}` responses rather than fetching them before every call.
- **Re-read instead of re-running.** `GET /v1/results/{id}` returns a stored result for free, without a new upstream call.

## Upstream limits are not your limits

Upstreams have their own rate limits. When an upstream limits us, the router treats it as a failed attempt and retries automatically; you do not get a `429` for it. If every attempt is limited at once, the call fails with `502 all_sources_failed` and costs nothing. Retrying a little later usually succeeds.

## Need more?

If your workload needs a higher sustained rate, write to support@primaryapi.com with your expected requests per second and the APIs involved.
