Rate limits - SeeSaw Developer

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

{
  "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.