Rate Limiting

Request-rate limits for the Claret API and how to handle 429 responses.

The Claret API limits how many requests it accepts over time, separately from credit metering. 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 problem document:

{
  "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 429s, 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.

Reading X-RateLimit-Remaining on normal responses lets a client slow down before it gets throttled, which is smoother than reacting to 429s.

Related documentation

• API Credits & Usage — credit costs, a separate limit from request rate.

• Error Reference — full list of status codes.

• Common Recipes — batching patterns for large syncs.