Carillon docsRate limits
Request budgets, response headers, and retry delays.
Public API requests that pass bearer authentication carry rate-limit headers, including
successful responses and 429 refusals. Missing or invalid credentials are rejected before
these budgets are applied.
The headers
RateLimit: limit=600, remaining=597, reset=42
RateLimit-Policy: 600;w=60
RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 42RateLimit and RateLimit-Policy are the current IETF structured-field form. The three separate
headers are the older draft, which several clients still parse, so both forms are sent. reset
counts down in seconds; the policy's window is constant.
The budgets
| Key type | Per key | Per address |
|---|---|---|
| Secret | 600 requests per minute | Not applied |
| Mobile | 6000 requests per minute | 60 requests per minute |
| Session token (management) | 600 requests per minute | Not applied |
Mobile requests must fit both the per-key and per-IP budgets. A key can be shared by many installed app versions, and several devices can share an IP address.
Backing off
A refusal is 429 rate_limited, with the seconds to wait in the detail and in RateLimit-Reset.
For your own API client, wait for Retry-After before retrying. The mobile SDKs retry network
failures, 429 and 5xx using their own exponential backoff from one second to five minutes;
they do not currently use the server's reset headers. Other 4xx responses are not retried
for the same device state.
The server uses fixed windows. RateLimit-Reset gives the seconds until the current window resets.
For send requests, preserve the original Idempotency-Key and body when retrying.