---
title: "Cos’è una idempotency key? Retry API sicuri | BroadRouter"
description: "Una idempotency key è un ID univoco del client inviato con la richiesta, così un retry non ripete l’effetto, come un doppio addebito. Come funziona e l’header IETF."
url: https://broadrouter.com/it/glossary/idempotency-key/
lang: it
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Tradotto dall’inglese con l’aiuto dell’IA. [Leggi l’originale in inglese](https://broadrouter.com/glossary/idempotency-key/) (aggiornato il 2026-11-14).

# Chiave di idempotenza (idempotency key)

Aggiornato 2026-11-14

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](https://broadrouter.com/it/glossary/exponential-backoff/) 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](https://broadrouter.com/it/blog/hourly-llm-api-key-explained/). `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):

```bash
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](https://broadrouter.com/it/guides/errors-and-retries/) per sapere cosa ritentare lì, e [rate limit](https://broadrouter.com/it/glossary/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.

## Vedi anche

-   [Backoff esponenziale (exponential backoff)](https://broadrouter.com/it/glossary/exponential-backoff/) (termine)
-   [Rate limit (limite di frequenza)](https://broadrouter.com/it/glossary/rate-limit/) (termine)
-   [Chiave API (API key)](https://broadrouter.com/it/glossary/api-key/) (termine)
-   [Concorrenza (concurrency)](https://broadrouter.com/it/glossary/concurrency/) (termine)
-   [Codici di errore di BroadNet Inference e quando ritentare](https://broadrouter.com/it/guides/errors-and-retries/) (guida)
-   [Limita le chiavi API ai tuoi server con le allowlist di IP](https://broadrouter.com/it/guides/api-keys-ip-allow-lists/) (guida)
-   [Agenti di lunga durata: timeout, retry e checkpoint che reggono](https://broadrouter.com/it/blog/long-running-agents-timeouts-retries/) (articolo)
-   [Chiave API LLM oraria: un prezzo fisso all’ora, spiegato](https://broadrouter.com/it/blog/hourly-llm-api-key-explained/) (articolo)

Provalo sul tuo carico di lavoro reale. I nuovi account partono con USD 5 di credito per Gemma e trascrizione. DeepSeek, GLM e Qwen3.8 richiedono una ricarica.

[Inizia](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-glossary-idempotency-key&utm_content=page-cta) ·

**Fonti**

-   [IETF HTTPAPI, The Idempotency-Key HTTP Header Field (Internet-Draft)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
-   [AWS Builders’ Library, timeout, retry e backoff con jitter (idempotency token)](https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter)
-   [Riferimento API di BroadNet Inference, chiavi orarie (idempotenza con request\_id) (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-glossary-idempotency-key&utm_content=sources#hourly-keys)
