How rate limiting works
Rate limits are applied per workspace, per endpoint, per minute, on a rolling basis. When the number of requests to a given endpoint in a given minute exceeds your allowance, further requests in that window are rejected with anHTTP 429 Too Many Requests response until the window resets.
A few principles worth internalizing up front:
- Limits are scoped to the workspace, not to the API user or API key. All keys and co-signers operating in the same workspace draw from the same pool. Adding API users does not increase your limits.
- Limits are enforced on peak bursts, not averages. A workspace that averages well under its limit can still receive 429s if requests cluster into a single minute. Design for your busiest minute, not your daily average.
- Limits vary by endpoint and are metered independently. Different endpoints have different allowances based on how costly they are to serve. A heavy reporting or export call is limited far more tightly than a simple read. Because each endpoint is metered on its own, exhausting the allowance on one does not affect your ability to call others.
Higher limits follow your license. Your workspace’s allowances are tied to your Fireblocks license tier. If you need more headroom, that is handled through a license change rather than a per-endpoint override. Reach out to your Fireblocks account team to discuss the right fit for your workload.
Rate limits are not transaction limits
Rate limits govern API request throughput: how many calls per minute your workspace can make. They are entirely separate from transaction count limits, which are commercial terms defined in your contract. Staying within your rate limit has no bearing on your transaction allowance, and vice versa.Handling a 429 response
When you exceed a limit, the API returns:
These headers are returned on
429 responses only. Successful responses do not carry limit or remaining-quota headers, so treat the 429 itself as the signal to slow down rather than trying to track remaining quota ahead of time.
Recommended retry strategy
Implement exponential backoff with jitter on any429 (and on 5xx) responses:
- On a
429, wait for the number of seconds given inRetry-Afterbefore retrying (falling back to a base delay of about 1 second if it is ever missing). - If the next attempt also fails, double the wait time on each subsequent retry.
- Add a small random jitter to each delay so that multiple clients backing off simultaneously don’t retry in lockstep.
- Cap the maximum delay and the total number of retries to avoid unbounded waiting.
Best practices to stay within limits
Prefer webhooks over polling. Instead of repeatedly pollingGET endpoints to detect changes (for example, checking transaction status in a loop), subscribe to webhook notifications and react to events as they arrive. This is the single most effective way to cut read volume.
Smooth out bursts. If you submit work in batches, spread the requests across the minute rather than firing them all at once. A queue with a steady drain rate keeps you under the per-minute ceiling far more reliably than bursting.
Right-size write-heavy workloads. Signing- and write-heavy integrations tend to hit their limits first, since write operations are metered more tightly than reads. If writes are your binding constraint, audit whether every one is necessary and whether any can be batched or deferred.
Cache where you can. Data that changes infrequently, such as supported assets, vault structure, and network connections, can be cached locally instead of re-fetched on every operation.
Back off, don’t hammer. Treat a 429 as a signal to slow down, not as a transient error to retry instantly. Aggressive immediate retries make congestion worse and extend the time until your window clears.