429 rate-limit responses on the API

429 rate-limit responses on the API

The /v1 API caps every key at 60 requests per minute, measured on a sliding window with a burst allowance of about 100. Cross the ceiling and the API returns HTTP 429 with a Retry-After header that tells you exactly how long to wait before retrying. Respect the header, back off exponentially on repeated 429s, and design your client not to fan out uncontrollably.

429s never count against your monthly line-item budget. Only successful requests are billed.

How to handle a 429

1. Read the Retry-After header. It is either seconds (an integer) or an HTTP date. Sleep at least that long.
2. Retry the same request unchanged. 429 is not a client bug; the request itself is fine.
3. If the retry also 429s, double the sleep and try again. Do not exceed five retries.
4. If a fifth retry still 429s, log the event and stop retrying. Something is wrong on your side (a runaway job) or on ours (an ingest surge). Contact support.
5. On success, resume normal traffic.
6. Never spin-poll without a sleep. Even without 429, tight loops burn quota and eventually get flagged.

For batch operations, prefer /v1/calc/bulk with async mode over fanning single /v1/calc requests. The bulk executor runs inside our infrastructure without hitting the rate limit.

Designing to stay under the limit

Client throughput of one request per second sits comfortably under the 60-per-minute cap and leaves headroom for retries.

For high-volume ingestion, batch calls: one /v1/calc/bulk call replaces up to 500 individual calls and counts as one request against the limit.

For lookup patterns, cache the result. HS classifications and country-hs rate lookups rarely change intra-day; caching for an hour on your side costs nothing and cuts API traffic by orders of magnitude.

Frequently asked questions

Can I request a higher limit

Enterprise customers can. Pro through Business are on the standard 60-per-minute cap.

Are 429s counted against my monthly line-item budget

No. Only successful runs are billed.

Does async bulk have its own rate limit

Async submission counts as one request against the same per-minute limit. The job itself runs server-side without touching the rate limit.

Why 60 and not higher

Balances fair use with protecting the upstream tariff data providers from stampeding client patterns. The cap is generous for interactive use and comfortably beatable via bulk for batch use.