Rate limits

Limits apply per account: all your keys share them, so more keys don't mean more requests.

What	Limit	Counted per
Reads: every GET, plus `POST /v1/orders/preview` and `POST /v1/shipments/estimate`	120 a minute	Account (all your keys together)
Writes: every other POST and PATCH	30 a minute and 2,000 a day	Account (all your keys together)
Failed key attempts: malformed, unknown, revoked or no longer valid keys	30 an hour and 200 a day	Network (IP address); a valid key is never blocked by this

A minute window starts at the start of each minute, and the day window at midnight UTC.

Response headers

Responses to requests that pass the key check carry:

Header	Meaning
`RateLimit-Limit`	Requests allowed in the current one-minute window for this kind of request (reads or writes).
`RateLimit-Remaining`	Requests left in that window.
`RateLimit-Reset`	Seconds until the window resets. It is a number of seconds, not a timestamp.

The headers show the one-minute window. The exception is a 429 caused by the daily write limit: there RateLimit-Limit is 2,000, and RateLimit-Reset and Retry-After count the seconds to midnight UTC. Otherwise the daily limit isn't shown.

The headers are missing when the key check fails (401 invalid_api_key, 403 api_not_enabled, 403 account_action_required) and on 404 and 405 answers for unknown paths.

When you hit a limit

You get 429 rate_limited with Retry-After, the number of seconds to wait. Wait at least that long before the next request of the same kind. Reads and writes are counted separately, so hitting the write limit doesn't stop reads.

A write refused by a rate limit doesn't count towards the daily limit, so a client that retries too early can't use up the day. Writes refused by later checks, such as validation, do count.

Staying under the limits

Use Webhooks instead of polling where you can.
When you poll orders, use updatedSince (Incremental sync) instead of reading every page each time.
Spread bulk work out and watch RateLimit-Remaining.
On 429, wait for Retry-After; after repeated 429s, slow down further.