Rate Limits
Limits are applied per API key and per endpoint. Your key’s traffic never consumes another customer’s allowance, and spending the budget on one endpoint doesn’t affect the others. Most endpoints enforce no limit today. The ones that do are listed below, and they return the rate limit headers on every response — not just on a 429 — so a client can pace itself before it is ever turned away.Limits can change as the API evolves. Read the response headers rather than hardcoding the
numbers on this page.
Response headers
Example response headers
Limited endpoints
Request rate
How many requests you may send per unit of time.Concurrent requests
Bulk endpoints limit how many of your requests may be in flight at the same time, rather than how many you send per second. A bulk call does a lot of work per request, and the cap keeps one client from occupying every worker.Concurrency limits are about parallelism, not pacing. Send bulk calls from a pool of at most 10
workers and you will never see a
429 from them, however long each call takes.
These responses carry Retry-After but no X-RateLimit-* headers — there is no window to
report on.When you hit a limit
The API answers429 Too Many Requests.
Retry-After header. Wait that long before retrying — retrying sooner just
earns another 429.
Handling 429 correctly
HonourRetry-After when it is present, and back off exponentially with jitter when it isn’t.
Jitter matters: without it, a fleet of clients that all got throttled retries in lockstep and
throttles itself again.
Staying under the limits
Use the bulk endpoints
Use the bulk endpoints
One bulk call carrying 500 shipments costs a single request against the limit; 500 individual
calls cost 500. See Create Requests Bulk.
Read the headers as you go
Read the headers as you go
X-RateLimit-Remaining tells you how much budget is left before you spend it. Slowing down at
a low remaining count is cheaper than recovering from a 429.Cap your own concurrency
Cap your own concurrency
Size your worker pool to the concurrency limit of the endpoint you are calling — 10 for the
bulk endpoints — instead of firing every request at once and retrying the rejections.
Spread scheduled jobs
Spread scheduled jobs
Nightly syncs that all start exactly at 00:00 pile into the same window. Starting them at a
random offset within a few minutes removes the spike without changing the total work.