Rate Limits

Understand the EasyRoutes API's rate limit, how to read the response headers, and how to handle HTTP 429 responses.

The EasyRoutes API limits how many requests each API client can make, to keep the API responsive and prevent abuse. Limits are scoped to your API client, i.e., the client ID tied to your access token, not to your shop or IP address. If you exceed your limit, requests are rejected with HTTP 429 Too Many Requests until your allowance recovers.

Your rate limit

Each API client gets a steady allowance of 10 requests per second, plus a burst allowance of up to 120 requests for short spikes above that rate.

Requests are limited using a leaky bucket: each client's bucket holds up to 120 requests, drains by one for every request you make, and refills at 10 requests per second when you're not making requests. As long as your average request rate stays near or below 10 requests per second, brief bursts above that rate are absorbed by the bucket instead of being rejected. Sustained traffic well above 10 requests per second will eventually exhaust the bucket and start being rejected.

Response headers

Every authenticated response includes headers describing your current rate limit state:

Header	Meaning
`RateLimit-Limit`	Your total request budget — the size of the bucket.
`RateLimit-Remaining`	Requests left in the bucket before you're rejected.
`RateLimit-Reset`	Seconds until the bucket fully refills back to `RateLimit-Limit`.
`Retry-After`	Seconds until your next request would be allowed. Only present on a rejected (`429`) response.

HTTP/1.1 200 OK
RateLimit-Limit: 120
RateLimit-Remaining: 87
RateLimit-Reset: 4
Content-Type: application/json

Check RateLimit-Remaining on every response and slow down proactively if it's trending toward zero, rather than waiting to be rejected.

When you're rate limited

A request that exceeds your rate limit is rejected with HTTP 429 Too Many Requests:

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 12
Retry-After: 1
Content-Type: application/json

{
  "code": 8,
  "message": "rate limit exceeded"
}

Retry-After tells you exactly how many seconds to wait before your next request is likely to succeed.

Handle rate limits gracefully

Read RateLimit-Remaining on every response and slow down before you run out, rather than waiting for a 429.
On a 429, wait at least Retry-After seconds before retrying — don't retry immediately.
Use exponential backoff with jitter for repeated 429s, to avoid a thundering herd if multiple processes share the same API client ID.
Batch requests and prefer webhooks over polling — see Performance best practices — to naturally stay well under the limit.

response=$(curl -s -D - -o /tmp/body \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://easyroutes.roundtrip.ai/api/2024-07/routes)

status=$(echo "$response" | head -n 1 | awk '{print $2}')
if [ "$status" = "429" ]; then
  retry_after=$(echo "$response" | grep -i '^Retry-After:' | awk '{print $2}' | tr -d '\r')
  echo "Rate limited, retrying after ${retry_after}s"
  sleep "$retry_after"
  # retry the request
fi

Your rate limit

Response headers

When you're rate limited

Handle rate limits gracefully

On this page