# Idempotency

Send an `Idempotency-Key` header with a `POST` and you can retry it after a timeout without creating the same thing twice.

## Why it matters

When a request to create something times out, you cannot tell whether it
failed or whether only the answer got lost. Retrying blindly could record the
same transaction twice. An idempotency key makes the retry safe: the API
remembers the first answer and repeats it.

## How to use it

Generate a unique value for each operation, a UUID for instance, and send it as
a header. Send the same value again when you retry that operation:

```bash
curl -X POST https://whisper.money/api/v1/transactions \
  -H "Authorization: Bearer $WHISPER_MONEY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2f4c1e-5d3a-4e7b-8c6d-0a1b2c3d4e5f" \
  -d '{
    "account_id": "0199a3f4-1d2e-7c3b-8a4f-5e6d7c8b9a01",
    "description": "Coffee",
    "amount": -250,
    "transaction_date": "2026-01-31"
}'
```

The header is optional, works on every `POST`, and is ignored on other methods.
`PATCH` and `PUT` are safe to repeat already, and repeating a `DELETE`
only answers `404` the second time.

## What happens on a retry

- **The first request succeeded.** The API sends back the same status and body
  without running the request again, with the header `Idempotent-Replayed:
true`. Keys are remembered for 24 hours.
- **The first request is still running.** The API answers `409` with the code
  `idempotency_conflict`. Wait a moment and retry.
- **The first request failed.** Errors are not remembered, so the retry runs
  again. You can fix the body and resend it with the same key.
- **Same key, different request.** Reusing a key with another path or body
  answers `422`, with the error under `Idempotency-Key`.

Keys belong to you: another user sending the same value does not collide with
yours.

A key must be between 1 and 255 characters; anything else answers `400` with
the code `invalid_idempotency_key`.

---

Full documentation index: https://whisper.money/documentation.md?lang=en