Header Idempotency-Key

Usa Idempotency-Key per riprovare una richiesta senza creare un'operazione duplicata. La garanzia è l'accettazione esattamente una volta: entro la finestra di conservazione di 3 ore, i nuovi tentativi con la stessa chiave e una richiesta identica devono risolversi nell'operazione originale, anche se ne hai perso la risposta. Per la strategia dei nuovi tentativi, consulta Idempotenza.

Header della richiesta

Le mutazioni con ambito di spazio di lavoro o organizzazione supportano la riproduzione delle risposte descritta di seguito. Le operazioni limitate all’utente, le operazioni non autenticate prive di ambito e i flussi non la utilizzano. Le operazioni con un contratto di riproduzione separato definiscono il proprio comportamento nella rispettiva pagina di riferimento.

Se ometti l’header o invii un valore vuoto, la richiesta viene elaborata normalmente senza deduplicazione. Negli endpoint che dichiarano questo header, una chiave più lunga di 255 caratteri restituisce 422 con il codice E01001 ValidationError.

Le chiavi hanno come ambito il tuo spazio di lavoro, o la tua organizzazione per gli endpoint a livello di organizzazione, e vengono conservate per circa 3 ore. Dopo questo intervallo, una richiesta che riutilizza la chiave viene elaborata come una nuova richiesta.

Semantica della risposta

Una risposta riprodotta è byte per byte identica all'originale (stesso status code, stesso body), distinguibile solo dall'header aggiuntivo:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

"Identical request" comprende il metodo, l’endpoint, i parametri del percorso e della query e il corpo originale della richiesta. Una differenza in questi valori, inclusi gli spazi in JSON, provoca E01005. I caricamenti multipart confrontano i nomi delle parti, i nomi dei file e i contenuti; i delimitatori e l’ordine delle parti non influiscono sulla riproduzione. Entrambi gli errori 409 vengono restituiti nella risposta di errore standard.

Le risposte conservate possono includere rifiuti 4xx. Usa una nuova chiave quando correggi una richiesta: se il rifiuto è stato conservato, un tentativo senza modifiche lo riproduce, mentre una richiesta modificata restituisce 409 E01005 IdempotencyKeyReuse.

In caso di timeout o di 5xx, riprova con un backoff limitato usando la stessa chiave e una richiesta identica entro tre ore. La garanzia di accettazione esattamente una volta vale anche se la risposta originale è andata persa. E01033 IdempotencyUnavailable indica che questo tentativo non è stato eseguito; non descrive l'esito di un tentativo precedente. Mantieni la chiave a ogni nuovo tentativo.

Per l'invio di un messaggio, l'accettazione esattamente una volta significa un solo invio accettato tra i nuovi tentativi corrispondenti. Controlla lo stato del messaggio per confermare la consegna. Dopo tre ore, verifica l'esito dell'operazione originale prima di inviare di nuovo: una chiave scaduta o una nuova chiave possono creare un'altra operazione.

Comportamento degli SDK

Gli SDK ufficiali allegano un UUID Idempotency-Key generato automaticamente a ogni richiesta mutante: viene creato una volta per chiamata logica e riutilizzato in tutti i nuovi tentativi di quella chiamata. Puoi fornire la tua chiave per ogni chiamata (idempotencyKey in TypeScript, option.WithIdempotencyKey in Go, idempotency_key in Python, new RequestOptions(idempotencyKey: ...) in PHP) quando un'operazione logica coinvolge più chiamate SDK. Per rilevare una riproduzione, leggi l'header di risposta Idempotency-Replay tramite l'accessor dei metadati di trasporto di ogni SDK: .withResponse() in TypeScript, option.WithResponseInto in Go e with_raw_response in Python.

Correlati

• Concetti di idempotenza: strategia dei nuovi tentativi, progettazione delle chiavi e limiti di riproduzione
• Risposte di errore: la risposta di errore che racchiude E01004 e E01005
• Messaggi email: l'endpoint di invio, il caso d'uso più comune per una chiave
• Concetti degli SDK: generazione automatica delle chiavi e retry