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

# Idempotency

> Retry a create without recording it twice.

A network error can hide whether a create reached Visor. Send an `Idempotency-Key` header with every `POST`, and send the same key when you retry. Visor then records the transaction only once.

```http theme={null}
Idempotency-Key: 2026-10-01-padaria
```

## How Visor uses the key

Visor stores the key on the transaction. A key is unique in its account.

| Request | Response |
| - | - |
| A new key in the account | Visor records the transaction and returns `201` with `idempotent-replayed: false`. |
| The same key again in the same account | Visor records nothing and returns the transaction it already has, with `idempotent-replayed: true`. |
| The same key with a different `amount`, `type`, `description`, `transacted_at`, or `category_id` | `409 IDEMPOTENCY_CONFLICT`. Visor records nothing. |
| Two requests with the same key at the same time | Visor records one transaction. Both requests receive it. |
| No key, or a key that is not 1 to 128 letters, digits, or `-` `_` `.` `:` | `400 IDEMPOTENCY_KEY_INVALID` |

* A retry returns the transaction as it is now. If you edited it after the first request, the response shows the edit.
* A request that fails validation records nothing, so you can fix the body and retry with the same key.
* The key does not expire. After you delete the transaction, the same key records a new one.

## Choose a key

Use a value that identifies the event in your system, such as an invoice number or a row ID in your spreadsheet. A new random UUID per create also works, as long as your script keeps it for its retries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.