Per-second budget
Watch X-RateLimit-Remaining
Use it to see the next-second headroom before you run into a 429.
Rate Limits
Set throughput, concurrency, and recovery rules before you ship a client.
Tier matrix
Design the client for both throughput and in-flight ceilings. The API does not queue overflow work for you.
- Requests / sec
- Per API key
- Concurrent
- Hard cap per key
- Budget
- Monthly credits still apply
| Tier | Requests / sec | Concurrent | Monthly credits | Coverage |
|---|---|---|---|---|
| Free | 15 | 3 | 10,000,000 | BTC + km:US500 |
| Build | 50 | 10 | 80,000,000 | All |
| Pro | 150 | 20 | 400,000,000 | All |
| Enterprise | Custom | Custom | Unlimited | All |
Concurrency rules
Read the budget and throughput headers before you hit the ceiling.
Monthly budget
Watch X-Credits-Remaining
The monthly credit ceiling still applies even when the per-second window looks healthy.
Recovery and backoff
Read the reset headers and retry later. Do not build an unbounded retry loop.
Per-second reset
Read X-RateLimit-Reset
Wait for the next second window instead of blind retries.
Monthly reset
Read X-Credits-Reset
Read the reset timestamp before you decide whether the key can recover in time.
Queue control
Do not stack retries behind one exhausted key
If the key is exhausted, shed load or switch keys. Unbounded retries only add noise.
Client rules
Use simple client-side controls instead of debugging 429s later.
Monitor response headers
Every response includes X-RateLimit-Remaining and X-Credits-Remaining. Read them before you wait for a 429.
Limit concurrent requests
The in-flight cap is client-side work too. Use a semaphore or pool so the server never sees an avoidable burst.
Use cursor pagination
Follow next_cursor instead of splitting history into many small windows. It is cheaper and easier to reason about.
Cache slow-changing routes
Instruments and freshness are 1-credit routes. Cache them for a few minutes instead of refetching on every pass.
Use aggregation intervals
For funding, open interest, and price history, ask for 1h, 4h, or 1d aggregates when raw rows are not required.
Prefer WebSocket for live loops
A live subscription often replaces hundreds of REST calls per minute and keeps your request budget cleaner.
Back off on 429
Read the reset headers and retry later. Immediate retries on an exhausted key just waste time.