# Rate limits

> How many requests you can make and what to do when you hit the limit.

To keep Tirver fast for everyone, the API limits how often each key can call it.

## The limits

- Each key can make **120 requests per minute**, counted over a sliding window. REST and MCP requests made with the same key share this limit.
- `POST /api/v1/ask` and the MCP `ask` tool are also limited to **10 per minute** per key, on top of the 120.
- A request body can be up to 256 KB. A larger one gets `413` with the code `payload_too_large`.

Limits are counted in memory by each server instance, so they are best effort rather than an exact global quota. Plan for the numbers above and rely on the response headers.

## Headers

Every authenticated response carries these headers.

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | The limit that applies. |
| `X-RateLimit-Remaining` | Requests left in the current window. |
| `X-RateLimit-Reset` | Seconds until the oldest request in the window leaves it. |

## When you go over

The API answers `429 Too Many Requests` with the code `rate_limited` and a `Retry-After` header that gives the number of seconds to wait. A `429` can also mean the AI agent is busy.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{ "error": { "code": "rate_limited", "message": "Too many requests. Try again in 12 seconds.", "request_id": "req_3f9c0a1b22d4e5f6" } }
```

Wait that long, then retry the same request. Keep waiting longer after repeated `429` responses.

## Good habits

- **Always honour `Retry-After`.** It is more precise than any guess.
- **Back off.** Double the wait after each failure, and add a little random jitter so many workers do not retry at the same moment.
- **Page with `limit=100`.** Fewer, larger requests use less of your allowance. See [pagination](https://tirver.com/help/api/pagination.md).
- **Do not poll.** If you check for new conversations every second, check every minute instead.
- **Cache what rarely changes,** such as articles and customer details.

See [errors](https://tirver.com/help/api/errors.md) for a retry helper you can copy.

Source: https://tirver.com/help/api/rate-limits