Guide
Idempotency
Safe retries for anything that creates or moves value.
Every endpoint that creates or moves value requires an Idempotency-Key header. Use a fresh UUID per logical operation, and reuse that same key for every retry of it.
POST /v1/transfers
Idempotency-Key: 6f1a2c30-7b2e-4d64-9f0e-3ee1f7f6b2c9
- Retrying with the same key and the same payload replays the original response. No second transfer, no second card.
- Reusing the key with a different payload returns
IDEMPOTENCY_KEY_REUSED. - Retrying while the first attempt is still running returns
IDEMPOTENT_REQUEST_IN_PROGRESS; back off and retry. - Omitting the header on an endpoint that requires it returns
IDEMPOTENCY_KEY_REQUIRED.
This matters most when a call fails with PROVIDER_UNAVAILABLE: the partner may have accepted the instruction without confirming it. Always retry such calls with the original key rather than issuing a new instruction.
Next
Pagination