Idempotency

Send Idempotency-Key (8–255 characters [A-Za-z0-9._:-], a UUID v4 is ideal) on POSTs; it is required on money-moving operations (payments, transfers, add money, exchanges, scheduled payments, mandates, collections, bulk payments, recipients, funds requests). Operations that require it show the Idempotency-Key required badge in the reference.

• One key per logical operation; reuse the same key when you retry the same request.
• Same key + same body within 24 h: the stored response is returned with Idempotency-Replayed: true; nothing happens twice.
• Same key + different body: 422 idempotency-key-reused. While the first request still runs: 409 idempotency-key-in-use with Retry-After.
• 5xx responses are not stored: retry with the same key.
• Responses that contain a one-time secret (POST /api-keys, POST /integrator-webhooks) are never replayed; do not retry those blindly: list and delete duplicates instead.

Optimistic concurrency

Updates of versioned resources need If-Match with the ETag from your last read. A stale value is 412 precondition-failed; a missing header is 428 precondition-required.