> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/api-guide/rate-limiting.md).

# Rate Limiting

The Claret API limits how many requests it accepts over time, separately from [credit metering](/api-guide/credits-and-usage.md). Limits use a **token-bucket** model: each bucket holds a number of request "tokens" up to its capacity, and refills at a steady rate. Each request spends one token; if the bucket is empty, the request is rejected with `429`.

## Limits

Three buckets apply, and a request must satisfy all that are relevant to it.

| Bucket      | Burst capacity | Sustained rate                        | Applies to                                     |
| ----------- | -------------- | ------------------------------------- | ---------------------------------------------- |
| Per token   | 10 requests    | 2 requests / second                   | Every request, scoped to the individual token. |
| Per tenant  | 50 requests    | 17 requests / second                  | All tokens for a tenant combined.              |
| Per compute | 3 requests     | \~1 request / 6 seconds (10 / minute) | Compute and workflow endpoints only.           |

In practice:

* A single token can burst up to **10 requests**, then settles to **2 requests per second**.
* Across all of a tenant's tokens, throughput is capped at roughly **17 requests per second**.
* Expensive **compute and workflow** endpoints (supply plan generation, forecasts, inventory/sales sync) are additionally limited to a burst of **3** and about **10 per minute**, because each one triggers significant downstream work.

## Rate-limit headers

Successful responses include the current state of the per-token bucket:

| Header                  | Meaning                      |
| ----------------------- | ---------------------------- |
| `X-RateLimit-Limit`     | The token bucket's capacity. |
| `X-RateLimit-Remaining` | Tokens left in the bucket.   |

When a request is rejected with `429`, two additional headers tell you when to retry:

| Header              | Meaning                                         |
| ------------------- | ----------------------------------------------- |
| `Retry-After`       | Seconds to wait before retrying.                |
| `X-RateLimit-Reset` | Unix timestamp when capacity becomes available. |

## Handling 429 responses

A throttled request returns `429 Too Many Requests` as an [RFC 9457](/api-guide/errors.md) problem document:

```json
{
  "type": "https://httpstatuses.com/429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after the period indicated by the Retry-After header.",
  "request_id": "..."
}
```

To handle it gracefully:

1. **Respect `Retry-After`.** Wait the number of seconds it specifies before retrying.
2. **Back off exponentially** if you hit repeated `429`s, rather than retrying in a tight loop.
3. **Spread bulk work out.** For large syncs, prefer fewer large payloads over many small requests. The workflow sync endpoints accept up to 100,000 records per call.

{% hint style="info" %}
Reading `X-RateLimit-Remaining` on normal responses lets a client slow down *before* it gets throttled, which is smoother than reacting to `429`s.
{% endhint %}

## Related documentation

* [API Credits & Usage](/api-guide/credits-and-usage.md) — credit costs, a separate limit from request rate.
* [Error Reference](/api-guide/errors.md) — full list of status codes.
* [Common Recipes](/api-guide/recipes.md) — batching patterns for large syncs.