Rate Limits

Overview

The Trakkr API limits how many requests it accepts per minute, so one busy caller cannot slow the service down for everyone else.

How the limit works

There is one kind of limit: a per-minute count on each endpoint, listed in the table below. It is the same on every plan. There is no burst allowance, no daily quota, and no higher tier that lifts these numbers. API access requires the Scale plan ($500/mo) or higher, but the plan does not change the per-minute figures.

Limits are counted per calling IP address, not per API key. Two keys calling from the same server share one budget, and so do all the services behind one NAT gateway or egress proxy. If a heavy job needs the full limit to itself, give it its own egress IP.

Per-Endpoint Limits

Different endpoints have different rate limits based on their computational cost. Write operations and resource-intensive endpoints have stricter limits.

Handling Rate Limits

When you go over, the API returns 429 Too Many Requests. The body holds one error string naming the limit you hit, for example Rate limit exceeded: 60 per 1 minute. Note that this is the one error that does not use the usual detail field.

Responses carry no rate limit headers. There is no X-RateLimit-Remaining, X-RateLimit-Limit, X-RateLimit-Reset or Retry-After to read, on any response including the 429. Plan around the published limits instead of measuring what is left.

Exponential Backoff

Exponential backoff means each retry waits longer than the last. Start above the one-minute window, then double, and add random jitter so clients do not all retry at exactly the same time:

1# Implement exponential backoff in shell
2attempt=1
3max_attempts=5
4
5while [ $attempt -le $max_attempts ]; do
6  response=$(curl -s -w "%{http_code}" \
7    -H "Authorization: Bearer $TRAKKR_API_KEY" \
8    'https://api.trakkr.ai/get-brands')
9  
10  status=$(echo "$response" | tail -c 4)
11  
12  if [ "$status" -eq 200 ]; then
13    echo "Success!"
14    break
15  elif [ "$status" -eq 429 ]; then
16    sleep_time=$((2 ** $attempt))
17    echo "Rate limited. Retrying in ${sleep_time}s..."
18    sleep $sleep_time
19    attempt=$((attempt + 1))
20  else
21    echo "Error: $status"
22    break
23  fi
24done

Best Practices