+++
title = "API Rate Limits"
weight = 82
updated = 2026-11-03

[extra]
nav_title = "Rate limits"
weight = 34
+++

Each token can make 60 requests a minute, across all endpoints of the Bonsai API v1 and the [legacy API](@/docs/api/legacy/_index.md) together. Creating clusters is further limited to 5 a minute per token.

## Rate limit headers

Every response carries a `RateLimit` header with what's left in the current window, and a `RateLimit-Policy` header with the limit, as in the [IETF RateLimit header fields draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/):

```
RateLimit: "token";r=42;t=18
RateLimit-Policy: "token";q=60;w=60
```

Here, 42 requests are left, and the window resets in 18 seconds. The policy allows 60 requests in a 60-second window.

## Going over the limit

A request over the limit gets a [`429 rate_limited`](@/docs/api/errors/index.md#rate_limited) with a `Retry-After` header giving the seconds to wait. Wait that long before retrying.

We're rolling these limits out gradually, so a request over a limit may still be served for now. Don't rely on that: stay under the limits, and wait for `Retry-After` before retrying a 429.

A few things count toward the limit that you might not expect:

- Polling an Action. Wait the seconds in its `Retry-After` header between polls: polling faster doesn't make it finish sooner. See [Actions](@/docs/api/actions/index.md#following-an-action).
- Replays of a request with the same `Idempotency-Key`. See [Retrying safely](@/docs/api/retrying-safely/index.md).

## Operations without a token

[`GET /v1`](@/docs/api/reference/account/index.md#get-api-root), the one operation that takes no token, is limited by IP address instead, to 60 requests a minute.

Too many requests from one IP address that fail to authenticate get a [`429 too_many_failed_authentications`](@/docs/api/errors/index.md#too_many_failed_authentications).