---
title: Idempotenza
description: Ripeta un acquisto in sicurezza, senza acquistare due volte.
sidebar:
  order: 4
---
Dopo un errore di rete, potrebbe non sapere se un acquisto è andato a buon fine. Per questo ogni `POST /offsets` richiede un’intestazione `Idempotency-Key`: un valore univoco per ogni acquisto, ad esempio un UUID.

```txt
Idempotency-Key: 7f8d0c6e-2b1a-4e9f-9d3c-5a6b7c8d9e0f
```

## Cosa succede quando riprova [#what-happens-on-a-retry]

| Cosa invia | Cosa riceve |
| --- | --- |
| Una nuova chiave | Un nuovo acquisto (`201`). |
| La stessa chiave e lo stesso corpo | Di nuovo il primo acquisto (`201`), con `Idempotent-Replayed: true`. Nulla viene acquistato due volte. |
| La stessa chiave e un corpo diverso | `409 idempotency_key_reused`. Usi una nuova chiave per un nuovo acquisto. |

La replica restituisce l’acquisto nel suo stato attuale, quindi il campo `status` potrebbe essere già passato da `processing` a `placed`.

## Da sapere [#good-to-know]

- Le chiavi contengono da 1 a 255 caratteri ASCII stampabili e le conserviamo in modo permanente, separatamente per ciascuna modalità.
- L’ordine delle chiavi nel corpo e gli spazi non contano: `{"kg":1,"reference":"a"}` e `{ "reference": "a", "kg": 1 }` sono la stessa richiesta.
- Un acquisto non riuscito (ad esempio `402 insufficient_balance` o un errore di validazione) non registra nulla. Dopo una ricarica, può riprovare con la stessa chiave.
- Due richieste con la stessa chiave nello stesso istante sono sicure: una effettua l’acquisto, l’altra riceve la replica.