> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Which calls require an Idempotency-Key, and what reusing one does.

Four calls create something that costs money or cannot be duplicated cleanly, and each one requires an `Idempotency-Key` header. Send one and a retry after a timeout returns the first result instead of creating a second business, account, recipient or payout.

The header is **required**, not optional. A call without it is rejected before anything is created.

## Where it applies

On all four the key is a **UUID** — anything else is rejected before the call reaches the resource.

* Create a user
* Create a virtual account
* Create a payout
* Create a recipient

No other write declares the header. Updating a user, requesting a quotation and the RFI calls take no key, so a retry there is not de-duplicated by one.

## What a key does

Generate a fresh key per operation you intend to perform — not per retry.

* **Same key, same body** — you get the original result back. Nothing new is created.
* **Same key, different body** — `409`. Nothing is created. Send a new key for a new operation, or resend the exact original body to get the first result.
* **Same key, first call still running** — also `409`. Retry the original request rather than starting a new one.
* **A key older than 24 hours** — forgotten. The record expires, and the same key creates a second operation.

<Warning>
  A `409` never means "it worked twice". It means the key is already spoken for and this request did nothing. Treat it as a signal to look up the first result, not as a failure to retry with the same key.

  One case has no first result to look up: if the original call died between taking the key and storing its response, the key stays held for the rest of its 24 hours and every retry answers `409`. Send a fresh key rather than polling.
</Warning>
