# Rate limits

> Requests per minute, per key, and what to do when you pass them.

Each key may make a set number of requests a minute. The limit depends on the key's environment:

| Key                   | Requests a minute, per key |
| --------------------- | -------------------------- |
| `htd_test_` (sandbox) | 10                         |
| `htd_live_` (live)    | 600                        |

The sandbox is for building and trying, not for load. A live key carries production traffic.

## What counts

- **Every REST request your key makes** counts, even one refused for a bad parameter.
- **Every MCP tool call** counts, because each one is a `/v1` request through the same gate.
- **The MCP handshake and the tool list** do not count.
- **`GET /v1/stats` and `GET /v1/coverage`** need no key and do not count.

## Past the limit

A request past the limit answers `429` with the code `rate_limited`. The `Retry-After` header says how many seconds to wait. Wait that long, then try again.

```bash
HTTP/2 429
retry-after: 12
x-request-id: req_4f8Kq2ZtW9mXb7Lc1RnP

{"error":{"code":"rate_limited","message":"...","request_id":"req_4f8Kq2ZtW9mXb7Lc1RnP"}}
```

A `429` is an error, so it is never billed.

## Staying under it

- Ask for full pages. A `limit` of 100 reads 4 times the records of the default page, for the same one request.
- Read the [change feed](https://data.heytownhall.com/docs/change-feed) for what changed, rather than reading every list again.
- Spread a large sweep over time, and keep a queue that honours `Retry-After`.