Rate limits and retries

REST API limits are 600 requests per minute per token, with bursts up to 100 requests in any 10-second window. Bulk endpoints don't count against this limit and have their own ceiling of 30 bulk requests per minute.

Every response includes three rate-limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp). When you hit a 429, the Retry-After header tells you exactly how many seconds to wait — respect it.

On the client, implement exponential backoff with jitter: start at 1s, double on each retry, cap at 32s, and add up to 50% random jitter to avoid thundering herds. Most HTTP clients (got, axios-retry, Stripe's SDK pattern) support this out of the box.

For webhook *consumers*, design for at-least-once delivery and idempotent handlers. Use the event id as a deduplication key in your database (UNIQUE (event_id)), and a 409 or 200 on duplicate is fine — we treat any 2xx as a successful delivery.