Skip to main content

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 answers 429 Too Many Requests.
Both carry a Retry-After header. Wait that long before retrying — retrying sooner just earns another 429.

Handling 429 correctly

Honour Retry-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

One bulk call carrying 500 shipments costs a single request against the limit; 500 individual calls cost 500. See Create Requests Bulk.
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.
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.
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.

Need a higher limit?

Tell us the endpoint, the throughput you need and the shape of your traffic (steady, or a daily batch) and we will size it with you. See Support.