Rate limits

Limits keep one integration from slowing down the others. They apply per API key, per API client, per account and per source address.

Request rate

These are the default limits for every account, and they are free: there is no charge for using the API.

Each limit is a steady rate with a burst. You may send up to the burst at once; after that, requests are allowed again as fast as the rate refills. Every request counts against each limit that applies to it, so all API clients and keys of one account share the per-account limit. The first limit to run out answers 429, and its Retry-After covers the longest wait.

What to do when you are limited

A request over a limit is refused with 429 rate_limit_exceeded and a Retry-After header in seconds. That answer is the only stable part of the contract: follow Retry-After instead of hard-coding a number.

• Wait at least Retry-After seconds before retrying.
• The per-source-address limit is applied at the edge, before the request reaches the API, so that 429 carries an edge_... request id instead of req_.... Handle it the same way.
• Spread batch jobs out; run them in parallel only as far as the limits allow.
• Retrying a write is safe only with the same Idempotency-Key.

Tier-2 daily caps

Each Tier-2 action also has a daily cap per account. When it is reached, the action answers 429 daily_cap_reached and Retry-After says when the cap resets.

The default daily caps are set before launch and published here then.

Size and batch limits