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

# Rate limits

> The per-key cap, how to read Retry-After, and how calls from an assistant are counted.

**Each key may make 60 calls a minute.** Go over it and the call is refused; wait
the number of seconds you are told, and the same request goes through.

## The cap is per key

Not per person, and not per account. Every key has its own window, so a busy
integration can never starve another one — and if one key misbehaves, revoking
that key restores the rest immediately.

The window rolls. It is not a clock that resets on the minute, so you cannot get
double the allowance by firing at a minute boundary.

## What a refusal looks like

```http theme={null}
HTTP/2 429
retry-after: 7
```

```json theme={null}
{
  "error": {
    "code": "tenant_mcp.rate_limited",
    "message": "You are sending requests faster than this API key is allowed to (60 per minute). Wait about 7 second(s) and retry — the same request will go through. Each key has its own window, so a busy integration never starves another one.",
    "retry_after_seconds": 7
  }
}
```

The wait is in the standard `Retry-After` header, in whole seconds, and repeated
in the body so you do not have to read headers to handle it. **Honour it rather
than retrying immediately** — a tight retry loop simply keeps the window full.

## Staying under it

* **Back off on `429` and retry once the wait has passed.** Most HTTP clients do
  this for you if you point them at `Retry-After`.
* **Use one key per place you call from.** Two systems sharing a key share one
  window; two keys never collide.
* **Batch your own work, not your requests.** Ask for a week's grid in one call
  rather than a day at a time.
* **Do not poll for changes you could wait for.** Polling every second burns the
  whole allowance on answers that did not change.

## How assistant calls are counted

An assistant talking to your account spends the same window, and **each message
costs one slot** — so a client that sends several at once spends several.

One request may carry at most **20 messages**. More than that is refused
outright:

```json theme={null}
{
  "error": {
    "code": "tenant_mcp.batch_too_large",
    "message": "This request carried 21 MCP messages in one batch; this endpoint accepts at most 20. Send your calls as individual requests — the current MCP specification does not use JSON-RPC batching, so one message per request is the expected shape."
  }
}
```

That is a `400`, not a `429`, because waiting will not help — the request itself
has to be split. In practice you will never see it: current assistant clients
send one message per request anyway.

## If you need more headroom

Before asking for a higher cap, check the three things that usually explain a
`429`: a retry loop with no backoff, two systems sharing one key, and polling
where one call would do. If none of those is it, contact support and say what
the integration does and how often — the fix is often a different shape of call
rather than a bigger number.