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

# Idempotency

> Usa header Idempotency-Key stabili sulle richieste di scrittura, così i tentativi restano sicuri e deduplicati.

# Idempotency

Tutti gli endpoint di mutazione `POST` e `PATCH` accettano un header facoltativo `Idempotency-Key`.

## Quando inviarlo

Usa una chiave di idempotenza quando:

* Un client potrebbe ritentare dopo un errore di trasporto.
* Un worker di coda potrebbe inviare la stessa operazione logica più di una volta.
* Un agente AI potrebbe rieseguire una mutazione dopo progressi parziali o retry degli strumenti.

## Pattern consigliato

* Genera una chiave stabile per ciascuna mutazione logica.
* Riusa la stessa chiave per i retry di quella mutazione.
* Cambia la chiave quando cambia la mutazione desiderata.

## Esempi

```http theme={null}
Idempotency-Key: create-project-song-1
```

```http theme={null}
Idempotency-Key: export-song-1
```

## Buoni confini

* Una chiave per creare un progetto.
* Una chiave diversa per esportare quel progetto.
* Un’altra chiave diversa per aggiornare le impostazioni del progetto.

Questo rende i retry sicuri senza deduplicare accidentalmente lavoro non correlato.