> ## 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.

# Idempotência

> Repita um registro sem gravá-lo duas vezes.

Um erro de rede pode esconder se um registro chegou ao Visor. Envie o header `Idempotency-Key` em todo `POST` e envie a mesma chave quando repetir. Assim o Visor registra a transação uma única vez.

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

## Como o Visor usa a chave

O Visor guarda a chave na transação. Uma chave é única na conta dela.

| Requisição | Resposta |
| - | - |
| Uma chave nova na conta | O Visor registra a transação e devolve `201` com `idempotent-replayed: false`. |
| A mesma chave de novo, na mesma conta | O Visor não registra nada e devolve a transação que já tem, com `idempotent-replayed: true`. |
| A mesma chave com outro `amount`, `type`, `description`, `transacted_at` ou `category_id` | `409 IDEMPOTENCY_CONFLICT`. O Visor não registra nada. |
| Duas requisições com a mesma chave ao mesmo tempo | O Visor registra uma transação. As duas requisições recebem essa transação. |
| Sem chave, ou uma chave que não tem de 1 a 128 letras, dígitos ou `-` `_` `.` `:` | `400 IDEMPOTENCY_KEY_INVALID` |

* Uma repetição devolve a transação como ela está agora. Se você editou a transação depois da primeira requisição, a resposta mostra a edição.
* Uma requisição que falha na validação não registra nada, então você pode corrigir o corpo e repetir com a mesma chave.
* A chave não expira. Depois que você exclui a transação, a mesma chave registra uma nova.

## Escolha uma chave

Use um valor que identifique o evento no seu sistema, como o número de uma nota ou o ID de uma linha da sua planilha. Um UUID aleatório novo por registro também funciona, desde que o script guarde esse valor para as repetições.


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