> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.awardspring.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.awardspring.com/_mcp/server.

# Rate limits

Requests are limited on a fixed window. Every response tells you where you stand, so a well-behaved client never has to discover the limit by hitting it.

| Header                  | Meaning                                                      |
| ----------------------- | ------------------------------------------------------------ |
| `X-RateLimit-Limit`     | Requests permitted per window.                               |
| `X-RateLimit-Remaining` | Requests left in the current window.                         |
| `X-RateLimit-Reset`     | When the window resets, as a UTC epoch timestamp in seconds. |
| `Retry-After`           | Seconds to wait. **Sent only on a `429`.**                   |

The first three appear on **every** response, including successful ones. Watch `X-RateLimit-Remaining` and slow down as it approaches zero rather than waiting to be refused.

## How the limit is partitioned

Your budget is scoped to your credential, not to the whole institution:

* **API key** — the limit is per key. Two keys for the same institution have independent budgets.
* **Bearer session** — the limit is per institution and user combined.

So a runaway job on one key cannot exhaust another integration's budget.

## When you are limited

A breach returns `429` with the JSON error object and `rate_limit_exceeded`:

```json
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded. Slow down and retry after the period indicated by the Retry-After header."
  }
}
```

Wait the number of seconds in `Retry-After`, then retry. Do not retry immediately, and do not retry on a fixed short interval — that turns one throttled client into a sustained one.

## Backing off well

Retry with exponential backoff and jitter, seeded by `Retry-After` rather than a constant of your own choosing. Two clients that both retry after exactly the interval will collide again on the next window; jitter is what stops a thundering herd rebuilding itself.

`429` is safe to retry. It means the request was never processed, so no partial write happened — and combining a retry with an [`Idempotency-Key`](/idempotency) means a `429` that was actually delivered still cannot produce a duplicate.

## Paging without burning budget

The cheapest way to stay inside the limit while reading a lot of data is a larger page rather than more requests. `limit` is capped at `100`, so reading 1,000 records costs 10 requests at `limit=100` and 40 at the default `25`. See [Pagination](/pagination).