Rate limits & idempotency
Rate limits keep the platform fast for everyone. Idempotency keys make it safe to retry money-moving requests without creating duplicates.
Rate limits
| Limit | Value |
|---|---|
| Requests per API key | 120 per minute by default. Set per key in the dashboard; the platform maximum is 1,200 per minute. |
POST /payments/{id}/verify | 6 per minute for each payment |
Over the limit, you get 429 rate_limited. Limits are counted per minute, so back off and retry after a short wait. Use webhooks instead of polling to stay well below the limits.
Idempotency
POST /payments and POST /payouts require an Idempotency-Key header: any unique string of 1–191 printable ASCII characters, such as your order ID or a UUID.
| Situation | Result |
|---|---|
| First request with a key | Runs normally. A successful (2xx) response is stored for 24 hours. |
| Same key, same body, after success | The stored response is returned again with header Idempotent-Replayed: true. Nothing new is created. |
| Same key, different body | 422 idempotency_key_reused |
| Same key while the first request is still running | 409 request_in_progress. Retry shortly. |
| First request failed (4xx/5xx) | Nothing is stored, so you can retry with the same key. |
Keys are scoped to your account and mode. Reusing a key after 24 hours starts a new request.
A second safety net: references
Each payment and payout reference must be unique within your account and mode. Even with a new idempotency key, a repeated reference returns 409 duplicate_reference with the ID of the existing object.
Recommended retry strategy
- Network error, timeout or 5xx: retry with the same idempotency key, with exponential backoff (for example 1s, 2s, 4s, 8s).
429: back off (for example 5s, 15s, 60s) and retry.- Other 4xx errors: do not retry until you have fixed the request.