Rate Limits

Every account has an overall ceiling (below). Individual routes carry their own, tighter per-route limits, counted per account over a rolling 60-second window. Whichever you hit first returns 429 — the per-route limits all sit inside the account ceiling, so a single route can never consume your whole budget.

Per-route write limits

Each is counted per account over a rolling 60-second window.

Per-route read limits

Account ceiling

Applied across every endpoint, per account.

Sandbox is deliberately tight. A load test that passes in sandbox at 100/min tells you nothing about production headroom — size against the production ceiling, and treat the per-route numbers above as sub-budgets within it.

Exceeded Limits

Exceeding a limit returns 429 in the standard merchant API error shape:

{
  "code": "RATE_LIMITED",
  "message": "Too many payout requests. Please try again later.",
  "requestId": "…"
}

Retry with exponential backoff. Do not assume rate-limit metadata headers are present on responses.

A 429 on a write means the request never ran, so retrying with the same Idempotency-Key is safe and is what you should do. See Idempotency.

Best Practices

1. Implement exponential backoff — When you receive a 429, wait before retrying
2. Cache responses — Reduce API calls by caching data where appropriate
3. Don't poll for payout status — Register a PAYOUT webhook and act on payout.updated. Read the payout back only to reconcile or to recover a missed delivery. Prefund top-ups have webhooks too (payout.prefund_completed), so the balance endpoint does not need polling either — read it back when an event fires.