# Rate limits

Two fixed-window limits apply to every authenticated request:

| Window | Counted per | Default limit |
| --- | --- | --- |
| 1 minute | API key | 120 requests |
| 1 day | Company — all its keys together | 100,000 requests |

The limits are counted per key and per company, never per IP address. The
windows are fixed, not sliding: a window's count starts over when it ends. The
values above are the defaults, which an installation can change, so drive your
behaviour from the response headers rather than from this table.

## Headers on every response

Every response, success or error, carries the state of the per-key minute
window:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | The requests the window allows. |
| `X-RateLimit-Remaining` | The requests left in it. |
| `X-RateLimit-Reset` | Seconds until the window resets. |

`GET /v1/whoami` counts toward the per-key minute limit but not toward the
company's daily budget; its `limits` object also tells the daily budget and how
much of it the company has spent today. Each operation says in the OpenAPI
document whether it counts (`x-muvia-quota`: `counted` or `free-daily`).

## MCP

The [MCP server](/guides/mcp-server) limits each key too. Reads share the REST
per-key per-minute limit (the same number); writes are limited to 30 per minute
per key. A refused call answers with an error result: «This key made too many
requests in a minute: try again in N seconds.» for reads, and «This key made too
many changes in a minute: try again in N seconds.» for writes.

## The 429 response

When a window is exhausted, the request answers `429`:

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit reached: 120 requests per minute per key",
    "status": 429,
    "hint": "Wait the number of seconds in the Retry-After header, then retry; X-RateLimit-Reset says when the window ends."
  }
}
```

with these headers:

| Header | Meaning |
| --- | --- |
| `Retry-After` | Seconds until the window resets. Wait at least this long. |
| `X-RateLimit-Limit` | The limit of the window that was exhausted. |
| `X-RateLimit-Scope` | Which window it was: `key` or `company`. |

## Backing off correctly

- Honour `Retry-After`: it is exact, not advisory. Retrying sooner only earns
  another 429.
- Add jitter when several workers share a key, so they do not retry in
  lockstep.
- Spread bulk work. 120 requests a minute is 2 a second per key; a nightly
  sync paced below that never meets the limit.
- Read dataset rows in large pages (`size` up to 1000) rather than many small
  ones.
- A `company` 429 means the daily budget is spent across **all** of the
  company's keys. Retrying will not help before `Retry-After`; coordinate with
  the company's other integrations. Issuing more keys does not raise it either.
