Docs / Core Guides / Idempotency

Idempotency

Every POST endpoint that mutates state or moves money requires an Idempotency-Key header.

Idempotency guarantees that an operation is executed only once, regardless of network dropouts, client timeouts, or automated retries.

http

POST /payments/organizations/org_99182/payouts
Idempotency-Key: 8f14e45f-ea0f-4b1a-9b0e-2c1d3e4f5a6b
Content-Type: application/json

How It Works#

Unique Logical Keys: Generate a unique key (such as a UUID v4) for every distinct logical payment or beneficiary creation.
Reuse on Retries: When retrying a failed or timed-out request, send the exact same Idempotency-Key and request body.
Replay Detection: If Avvio has already processed the request, the server replays the original response with an Idempotency-Replayed: true header rather than executing the action a second time.

Response Codes & Handling#

Response Code	Type / Header	Meaning	Correct Action
`400`	`IDEMPOTENCY_KEY_REQUIRED`	The header was omitted	Add the `Idempotency-Key` header and retry
`400`	`IDEMPOTENCY_KEY_INVALID`	Malformed format (must be 1–255 chars of `[A-Za-z0-9_.:-]`)	Use a standard UUID v4 string
`409`	`IDEMPOTENCY_KEY_CONFLICT`	The key was already used with a different request body	Do not retry. A different payload requires a new idempotency key
`409`	`IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS`	An identical request is currently processing	Back off exponentially and retry with the same key
`503`	`IDEMPOTENCY_UNAVAILABLE`	Ephemeral server storage issue; nothing was executed	Back off and retry with the same key
`200 / 201`	`Idempotency-Replayed: true`	The original result was returned from cache	Treat as a successful execution. Do not re-send

Timeouts are Unknowns, Not Failures#

IMPORTANT

A network timeout or HTTP 500 does not prove the payment failed. The payout may have been accepted and dispatched to the clearing network before the connection dropped.

If your client encounters a timeout or connection reset:

Do not create a new quote and send a new request with a new idempotency key. That initiates a second payment.
Do retry the identical request using the same Idempotency-Key.
Alternatively, query the payout by your reference or check GET /payments/organizations/{orgId}/events to observe the created payout.

Error Key Release vs Terminal Failures#

Validation Errors (4xx): If a request fails preliminary parameter validation (e.g. invalid currency format or missing field), the idempotency lock is released immediately. You can correct the payload and reuse the same key.
Payment Rail Failures: If a payout reaches the payment rail and is refused (e.g. invalid bank routing), this constitutes a terminal attempt. Retrying a new payout attempt requires generating a fresh idempotency key.