> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seesaw.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Per-key quotas, response headers, and how to handle 429s

Limits are enforced **per API key**, shared across both faces (REST and MCP
calls draw from the same budgets).

| Budget                               | Limit                                                                                          |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| General                              | **120 requests / minute**                                                                      |
| Search (`/search` + `search_topics`) | **30 requests / minute**, a dedicated extra budget — search calls also consume the general one |
| Daily                                | **10,000 requests / day**                                                                      |
| Active keys per user                 | 5                                                                                              |

Windows are fixed per minute/day. Occasional 429s are expected behavior at
the edges of a window — build retry logic rather than tuning to the exact
numbers.

## Response headers

Every REST response carries the state of the **binding minute window** (the
one that would reject you first):

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 22
```

`X-RateLimit-Reset` is **seconds until the window resets** (not a Unix
timestamp).

## When you hit 429

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "details": { "retry_after": 22 }
  }
}
```

The response also carries a standard `Retry-After: 22` header.

* **Wait `retry_after` seconds, then retry.** Add jitter if you run several
  workers on one key.
* Prefer exponential backoff for repeated 429s.
* Over **MCP**, a rate-limited call surfaces as a tool error naming the retry
  delay — agents should read it and pause rather than hammer.

## Staying under the limits

* Use `limit` (up to 100) and cursors instead of many small pages.
* Cache stable data (zones, contest schedules) on your side.
* Use `list_topics` for browsing; save `search_topics` (the tighter budget)
  for actual keyword lookups.