# Public API rate limits

Each API token has its own request budget per minute and per hour. A busy integration on one token never slows another token down. A request without a token shares one budget with every other anonymous caller.

## When a request is refused

A request over the budget answers `429` with the [error body](/api/errors), `code` `rate_limit_exceeded` and `retryable` `true`. Its `detail` names the limit and its window. Four headers say when to try again:

| Header | Value |
|---|---|
| `RateLimit-Limit` | The requests the window that refused this one allows. |
| `RateLimit-Remaining` | The requests left in that window: `0`. |
| `RateLimit-Reset` | Seconds until the window lets a request through again. |
| `Retry-After` | The same seconds as `RateLimit-Reset`. |

## Back off

<Stepper>

1. On a `429`, read `Retry-After`, or `RateLimit-Reset` when a proxy dropped it.
2. Wait that many seconds, then send the same request again.
3. When the wait is long, such as most of an hour, the hourly budget is spent: stop and resume later rather than holding the request open.

</Stepper>

The Terraform provider does this for you: it waits out a short `Retry-After` and reports a long one as an error.

## How it behaves

- The budget belongs to the token, whatever client or address sends it. A header such as `X-Client-Id` does not open a new budget.
- Only `Authorization: Bearer` carries a token. A token sent any other way, such as an `X-Api-Key` header, is not read, so an operation that needs a token answers `401`.
- A `429` is refused before the operation runs, so retrying it is safe for every method, a create included.
- Reading cost data with `limit=5000` costs one request per 5,000 rows; see [Pagination](/api/pagination).

## Related

- [Errors](/api/errors)
- [Pagination](/api/pagination)
- [Authentication](/api/authentication)