API problem detail
Invalid Idempotency Key
Description
This problem happens when an operation that takes an X-Idempotency-Key receives a malformed
one (the header was sent more than once, is not a valid UUID, or is not version 4) or receives none where
one is required. The key is required on the operations documented with it: creates, money-movement and
bundled request actions, bank-account $Verify, the branch bank-account and permission
replacements, and onboarding provisioning. Environment configuration determines enforcement for protected operations; send the header in both Test and Production. Three webhook
operations always require it in every environment: POST /DisbursementRequests/WebhookSubscriptions,
$Test, and $Redeliver.
The title is Invalid Idempotency Key. Depending on which layer refuses the request,
the type ends in /ProblemDetails/BadRequest or
/ProblemDetails/InvalidIdempotencyKey, so branch on errorCode
INVALID_IDEMPOTENCY_KEY rather than on the type or title.
Response errorCode: INVALID_IDEMPOTENCY_KEY.
Experience API error bodies also carry errorCode, resolution, and
traceId. Branch on errorCode, not on title or
detail; see fields on every error.
How to resolve
X-Idempotency-Key. Use a fresh key for each
distinct operation, and reuse the original key only when retrying the exact same operation and body
after an uncertain outcome.