# Rate limits & headers

Rate limits are applied **per organization**, across all of your keys and the MCP
server together — not per key.

## The limit

The limiter is a token bucket that holds **60 tokens** and refills at **1 token
per second**. In practice:

- You can burst up to **60 requests** back-to-back.
- Sustained throughput settles at about **1 request per second** as the bucket
  refills.

## Headers

Every response includes the current state of your window:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Bucket size (the ceiling) |
| `X-RateLimit-Remaining` | Tokens left right now |
| `X-RateLimit-Reset` | Unix time (seconds) when the bucket is full again |

Read `X-RateLimit-Remaining` and back off before you hit zero rather than waiting
for a `429`.

## When you're limited

Exceeding the limit returns `429 RATE_LIMIT_EXCEEDED` in the
[unified error shape](https://appmanai.com/docs/guide/errors.md), plus a `Retry-After` header giving the
number of seconds to wait:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 3
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000003
```

```json
{
  "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded" },
  "request_id": "req_..."
}
```

Honor `Retry-After`: sleep for that many seconds, then retry. Exponential backoff
on repeated `429`s is a good default for automated clients.

> **Rate limits vs credits**
>
> Rate limits cap how *fast* you call; [credits](https://appmanai.com/docs/guide/errors.md#insufficient-credits)
> cap how *much* you call. They're independent — you can have credits left and still
> be rate-limited, or be well under the rate limit and out of credits.