Rate limits

MCP calls

Calls to https://api.superbooks.io/mcp are limited to 120 requests per minute, counted per credential.

Per credential is the important detail: the budget belongs to the individual API key or OAuth access token, not to your team or your IP address. Two keys on the same team have independent budgets, so a noisy background job holding its own key cannot starve your interactive client.

The window is fixed rather than sliding, and it is anchored to your first request rather than to the clock. That first call opens a 60-second window, the whole budget belongs to that window, and it resets 60 seconds later — so the reset is not aligned to the top of the minute, and it does not trail your request history the way a sliding window would.

Dynamic client registration

POST /api/oauth/register is limited to 5 requests per hour per IP address.

Registration is public by specification, so the limit is deliberately tight. It is not a constraint you should meet in normal operation: register your client once and keep the client_id. Re-registering on every run is the mistake this limit exists to catch.

When you exceed a limit

You get 429 Too Many Requests, with a Retry-After header giving the seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Registration failures instead return the RFC 7591 error shape:

{
  "error": "too_many_requests",
  "error_description": "Too many registration requests; try again later"
}

Staying under the limit

Honour Retry-After. It tells you exactly how long to wait. Retrying immediately, or on a fixed short interval, just burns the next window too.

Back off exponentially, with jitter. If several workers share a key and all retry at the same moment, a fixed backoff re-synchronises them into the same spike. Randomising the delay spreads them out.

Page deliberately. List tools accept a limit (up to 100) and return a cursor. Requesting one large page costs a single call; requesting a hundred tiny ones costs a hundred.

Give separate workloads separate keys. Since the budget is per credential, a batch job with its own key cannot exhaust the budget your user-facing path depends on. It also means you can revoke one without disturbing the other.

Cache what does not change often. Category and tag catalogues, team details, and account lists are stable — re-fetching them inside a loop spends budget for an answer you already had.