Like most APIs, the Tracksuit API limits how many requests you can send in a short space of time. This keeps the service fast and fair for everyone who uses it. The limits are generous and everyday use rarely comes close. However, if your code fires requests in a tight loop, you can hit them.
This article explains what the limits are, how they're measured, and exactly what to do if you're ever rate limited.
The limits
What | Limit |
Steady rate | 5 requests per second |
Short bursts | Up to 10 requests at once |
Applies to | Each user (see below) |
âThe bucket analogy.
Picture a bucket that holds 10 tokens. Every request you make spends one token. The bucket refills at 5 tokens per second. Send steadily at 5 requests a second (or fewer) and you'll never run dry. Send a quick burst and you can spend up to 10 at once, but then you have to ease off while the bucket refills. Go faster than it can refill and the next request is turned away.
What "per user" means
The limit is tied to the user who created the API key. That's the person whose login generated the token in the Tracksuit dashboard.
All keys from the same user share one limit. If one person generates several API keys, every request made with any of those keys draws from the same bucket. Creating more keys does not give you more headroom.
Different users have separate limits. If two people on your team each generate their own key, each gets their own independent 5-per-second bucket.
If you're running a heavy, always-on integration and a single user's limit feels tight, the cleanest way to scale is to spread the work across separate Tracksuit users.
What happens if you go over
When you send requests faster than the limit allows, the API turns the extra ones away with an HTTP 429 Too Many Requests response. The successful requests are unaffected, only the ones over the line are rejected.
What you'll see | Value |
HTTP status |
|
Response body |
|
Rate-limit headers | None |
There is no Retry-After header. A 429 from the Tracksuit API does not include a Retry-After header, nor any X-RateLimit-* / RateLimit-* headers telling you how long to wait or how much budget is left. Don't build logic that depends on reading them. Instead, decide how long to wait yourself, using the backoff approach below.
What to do about a 429
A 429 is temporary. It just means "you're going too fast right now." The fix is simple: wait a moment, then retry. The safest way to do that is exponential backoff with jitter:
On a
429, wait a short pause (say 1 second) before retrying.If you get another
429, double the wait each time (1s â 2s â 4s â 8sâŚ).Add a little random jitter to each wait, so that if several jobs hit the limit together they don't all retry in lockstep.
Give up after a few attempts (e.g. 5) and surface the error, rather than retrying forever.
import time, random def with_backoff(make_request, max_attempts=5): for attempt in range(max_attempts): response = make_request() if response.status_code != 429: return response # Wait longer each time, plus a little randomness. wait = (2 ** attempt) + random.uniform(0, 1) time.sleep(wait) raise RuntimeError("Still rate limited after several retries")
429 is a status you can retry (alongside 500, 503 and 504). For the full picture of how to handle every status code and the shared error envelope, see How to handle API errors.
Staying under the limit
The best way to handle rate limits is to rarely hit them. A few habits keep you comfortably inside the budget:
Send requests one after another, not all at once. Firing 50 requests in parallel will trip the limit instantly; sending them in sequence usually won't.
Pace bulk pulls. When you're pulling a lot of data, aim for around 5 requests a second or fewer. A tiny pause between requests is enough.
Page sensibly. Use a large
page_sizeso you make fewer, bigger requests rather than many small ones. See How to handle pagination.Cache what doesn't change. Tracksuit data refreshes monthly, so there's no need to re-pull the same figures repeatedly within a run.
Common pitfalls
Firing requests in parallel. Kicking off many concurrent requests is the most common way to hit a 429. Send them sequentially, or limit how many run at once.
Hammering straight after a 429. Immediately retrying without waiting just earns you another 429. Always back off first, and lengthen the wait on each retry.
Spinning up extra API keys to get around the limit. Every key a single user creates shares the same bucket, so this doesn't help. The limit is per user, not per key.
Waiting on a Retry-After header. The Tracksuit API doesn't send one. Decide your own wait time with exponential backoff instead.