Rate Limits & Caching
Edge caching behavior, rate limits and handling 429.
The API is served behind Cloudflare. Three behaviors are worth knowing: date-range limit, edge caching and rate limiting.
Date-range limit
A single request may span at most 90 days (from–to). A wider range returns
400 Bad Request.
For longer periods, split the range into 90-day chunks and merge the results on your side.
Edge caching
Responses are cached at the Cloudflare edge per API key (30 minutes). Within that window, repeating the exact same query (same parameters, same key) may return from cache without hitting the origin.
What this means in practice:
- Re-fetching the same report is fast and cheap.
- Data can lag by up to ~30 minutes; it is not real-time.
- The cache is key-scoped — different keys never see each other's data.
Tip: Changing a single parameter (e.g. the
tosecond) produces a different cache key and bypasses the cache.
Rate limiting
To prevent abusive/automated traffic, requests are rate-limited at Cloudflare. If you
exceed the limit you'll get 429 Too Many Requests.
Handling 429
- Reduce request volume; cache results on your side where possible.
- Apply exponential backoff (e.g. 1s, 2s, 4s, 8s) before retrying.
- For bulk pulls, serialize requests or add delay between them — don't burst in parallel.
Related statuses
| Status | Meaning |
|---|---|
400 Bad Request | Date range exceeded 90 days (or another invalid parameter) |
429 Too Many Requests | Rate limit exceeded — retry with backoff |
5xx | Transient origin/edge error — retry after a short wait |
All error codes → Errors.