> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/developers/api/rate-limiting.md).

# Rate limiting

> How the BoxHero API limits request rates per team and how to back off and retry.

To keep the service stable for everyone, the BoxHero API limits how many requests a team can send.

## Limits are per team

All API tokens that belong to the same team share the same limits. Issuing more tokens in one team does not raise the limit.

## When you hit the limit

The API responds with `429` and an [error envelope](https://www.boxhero.io/docs/developers/api/errors) whose `type` is `/errors/too-many-requests`. The response headers tell you when you can try again:

| Header | Description |
| --- | --- |
| `Retry-After` | Seconds to wait before retrying |
| `RateLimit`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` | The current limit, the requests left, and when the limit resets |

Back off and retry after the time in `Retry-After`. If you send many requests in a row, spread them out instead of sending them all at once.

> **Note**
>
> Limits can change. Read them from the response headers rather than hard-coding a rate in your client.