400

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

Send exactly one well-formed UUID v4 in 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.
Back to all problem details