Rate limits

Request rate#

The values can change. Do not design your integration around the exact numbers. Handle 429 in every client.

Handle a 429 response#

1. If the response has Retry-After, wait that number of seconds.
2. If it does not, wait with exponential backoff: for example 1, 2, 4, then 8 seconds, up to a maximum.
3. Add random jitter to each wait, so that many clients do not retry at the same moment.
4. Retry with the same Idempotency-Key. See Idempotency.

function waitMs(attempt: number, retryAfter: string | null): number {
  if (retryAfter !== null) return Number(retryAfter) * 1000
  const base = Math.min(30_000, 1000 * 2 ** attempt)
  return base / 2 + Math.random() * (base / 2)
}

To stay under the limit:

• Use webhook events instead of polling. See Webhooks.
• Use limit=100 when you page through lists.
• Spread batch jobs over time.

Request limits#

A 504 does not tell you whether the operation ran. Retry with the same Idempotency-Key: if the first request completed, the retry returns its result.

Test your 429 handling in sandbox before you go live.