BroadRouter
Inizia

Chiave di idempotenza (idempotency key)

Aggiornato

Una chiave di idempotenza è un valore univoco, di solito un ID casuale come un UUID, che il client allega a una richiesta che modifica lo stato, come un pagamento o un acquisto. Se la stessa richiesta arriva di nuovo con la stessa chiave, il server restituisce il risultato originale invece di eseguire l’azione due volte.

Detto anche: chiave di idempotenza, idempotenza API, richiesta idempotente, retry idempotente, idempotency key, Idempotency-Key header, idempotency token, idempotent request, idempotent retry

La rete si rompe nel punto peggiore: dopo che il server ha agito ma prima che tu abbia ricevuto la risposta. Una chiave di idempotenza rende sicuro il retry.

Come funziona

Il client crea una chiave univoca per una singola azione voluta e la invia con la richiesta. Il server salva la chiave insieme al risultato. Se la stessa chiave arriva di nuovo, il server restituisce il risultato salvato invece di agire un’altra volta.

Il gruppo di lavoro IETF HTTPAPI sta standardizzando questo meccanismo come header di richiesta Idempotency-Key (draft 08, ottobre 2026, non ancora un RFC). Descrive la chiave come “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (traduzione: un valore univoco generato dal client, che la risorsa usa per riconoscere i retry successivi della stessa richiesta) e raccomanda un UUID o un ID casuale simile. I casi di errore della bozza:

Situazione Stato
Chiave mancante dove è obbligatoria 400 Bad Request
Richiesta originale ancora in corso 409 Conflict
Chiave riusata con un corpo diverso 422 Unprocessable Content

La Builders’ Library di AWS dice la stessa cosa dal lato client: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (traduzione: non è sicuro ritentare le API con effetti collaterali, a meno che non offrano idempotenza).

Perché è importante

I retry con backoff esponenziale sono una pratica standard, e molti SDK ritentano in automatico. Senza idempotenza, un retry dopo un timeout può creare due ordini o due addebiti. Con una chiave, ritentare è sicuro qualunque cosa abbia fatto il primo tentativo. Per questo è uno strumento centrale per agenti e script che comprano, prenotano o creano cose senza un umano che controlli.

Su BroadNet Inference

BroadNet usa questo schema per l’acquisto di chiavi orarie. POST /portal/keys/hourly accetta un request_id nel corpo JSON, e la documentazione afferma che “Idempotency is required for money safety” (traduzione: l’idempotenza è necessaria per la sicurezza dei pagamenti):

curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
  -H "Authorization: Bearer <portal-credential>" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"order-20260920-001","label":"kiosk-1"}'

Riusare un request_id non crea né addebita un’altra chiave. Dopo un timeout, una connessione interrotta, un 409 mint_in_progress o un 5xx, ritenta con lo stesso request_id. Una ripetizione restituisce already_issued: true e l’alias della chiave; solo la prima risposta andata a buon fine contiene la chiave in chiaro. La documentazione dice: “Never generate a replacement id until the original result is known.” (traduzione: non generare mai un id sostitutivo finché non conosci il risultato originale).

BroadNet non documenta una chiave di idempotenza per /v1/chat/completions né per le trascrizioni. Vedi codici di errore e retry per sapere cosa ritentare lì, e rate limit per capire perché i retry alla cieca possono peggiorare un 429.

Domande frequenti

Quando devo generare una nuova chiave di idempotenza?

Solo per una nuova azione voluta. Riusa la stessa chiave per ogni retry di un’azione, e non crearne una nuova finché non conosci l’esito del primo tentativo.

Le richieste di chat completion a un LLM hanno bisogno di una idempotency key?

Generare testo non ha effetti collaterali duraturi, quindi una richiesta di chat ripetuta di solito costa solo di nuovo dei token. La chiave conta per le chiamate che addebitano denaro o creano risorse. BroadNet la documenta solo per l’acquisto di chiavi orarie, non per le chat completion.

Cosa succede se riuso una chiave con un corpo di richiesta diverso?

La bozza IETF dice che il server dovrebbe rifiutarla con 422 Unprocessable Content, perché la chiave è già legata a un’altra richiesta.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity