Source: https://www.puesto.dev/docs/rate-limits
Markdown source: https://www.puesto.dev/docs/rate-limits.md
Description: Per-account request limits, the 429 response, and how to back off correctly.

# Rate limits



The API enforces a per-account request rate limit to keep the service fast and
fair for everyone. When you exceed it, requests are rejected with
`429 Too Many Requests` until the window resets.

## The limit [#the-limit]

The default limit is **300 requests per 60 seconds per account** — roughly
5 requests per second sustained. This is generous for
[changes-feed](/docs/changes-feed) polling and [jobs](/docs/api/jobs/search-jobs)
paging while stopping runaway loops.

## Per-account buckets [#per-account-buckets]

The limit is tracked **per account, not per API key**. All of an account's API
keys share a single bucket, so minting additional keys does not raise your
throughput — a request counts against the account regardless of which key made
it.

## The 429 response [#the-429-response]

When the limit is exceeded, the API returns a standard
[problem+json](/docs/errors) document with status `429`:

```json
{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded for this account. Retry after the interval in the Retry-After header."
}
```

The response includes a `Retry-After` header giving the number of **seconds** to
wait before retrying:

```
Retry-After: 60
```

## Handling 429s [#handling-429s]

* **Honor `Retry-After`.** When you receive a 429, wait at least the number of
  seconds it specifies before sending another request.
* **Back off exponentially** if you keep hitting the limit — increase the delay
  on each successive 429 rather than retrying in a tight loop.
* **Spread work out.** For large syncs, page steadily rather than firing bursts
  of concurrent requests.

## No usage headers (yet) [#no-usage-headers-yet]

The API does **not** currently return `X-RateLimit-Remaining`,
`X-RateLimit-Reset`, or similar headers — there is no way to read your remaining
quota ahead of time. Rely on the `Retry-After` header on a 429 and pace your
requests conservatively.