Developers
Public API rate limits
How the Costfluent Public API limits each token's requests, and how to back off when it answers 429.
Each API token has its own request budget per minute and per hour. A busy integration on one token never slows another token down. A request without a token shares one budget with every other anonymous caller.
When a request is refused
A request over the budget answers 429 with the error body, code rate_limit_exceeded and retryable true. Its detail names the limit and its window. Four headers say when to try again:
| Header | Value |
|---|---|
RateLimit-Limit | The requests the window that refused this one allows. |
RateLimit-Remaining | The requests left in that window: 0. |
RateLimit-Reset | Seconds until the window lets a request through again. |
Retry-After | The same seconds as RateLimit-Reset. |
Back off
- On a
429, readRetry-After, orRateLimit-Resetwhen a proxy dropped it. - Wait that many seconds, then send the same request again.
- When the wait is long, such as most of an hour, the hourly budget is spent: stop and resume later rather than holding the request open.
The Terraform provider does this for you: it waits out a short Retry-After and reports a long one as an error.
How it behaves
- The budget belongs to the token, whatever client or address sends it. A header such as
X-Client-Iddoes not open a new budget. - Only
Authorization: Bearercarries a token. A token sent any other way, such as anX-Api-Keyheader, is not read, so an operation that needs a token answers401. - A
429is refused before the operation runs, so retrying it is safe for every method, a create included. - Reading cost data with
limit=5000costs one request per 5,000 rows; see Pagination.