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.