Idempotency - Visor Personal API

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.

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.