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

# Idempotency keys

> Retry a write with the same key; Guile returns the original result

Send the same `Idempotency-Key` when you retry a write after a timeout. Guile
returns the original result instead of running the write twice.

## What you do first

1. Generate a new key for each distinct write you mean to run once (a V4 UUID is fine).
2. Put it on the `Idempotency-Key` header of the mutating call.
3. On retry of that same write, send the same key and the same body.

```http theme={null}
POST /businesses/business_34ad99/payouts
Idempotency-Key: 11715481-a337-4a46-a33e-3dcdc56c3b51
Content-Type: application/json

{
 "amount": "100.00",
 "currency": "USD"
}
```

Money writes that require a key include
[creating an instant payout](/api-reference/payouts/create-an-instant-payout-for-the-given-business).
Other mutating calls may accept a key optionally, check the operation.

## States that matter

| Outcome                     | What you do                                                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Success stored for this key | Guile replays the original response                                                                                          |
| Request still in flight     | You may see [Idempotency Request In Progress](/problems/idempotencyRequestInProgress): wait, then send the same key and body |
| Same key, different body    | [Idempotency Key Conflict](/problems/idempotencyKeyConflict): retry the original body, or use a new key for a new write      |
| Key older than 24 hours     | Replay state is gone; the same key starts a new request                                                                      |

Keys are scoped per operation. Changing the body with the same key does not
re-run the write with new parameters. Keys stay valid for **24 hours** for replay
on the operations that document that retention. They are not searchable. Keep the
resource id from the first success and use that for later reads.

## When a call fails

If the connection ends before a response arrives, treat the write outcome as
unknown. Retry the exact request with the same idempotency key so Guile can
return the original result instead of running a second write. Do not invent a
new key after an ambiguous timeout.

## Related paths

* [Appointments](/api-reference/Appointments/overview): creates need a key so a same-key retry can replay the first result
* [Payments](/api-reference/Payments/overview): card-present writes that move money
* [Problem types](/api-reference/problems): how to read a failure