Header Idempotency-Key

L’API di Bird supporta la deduplicazione facoltativa delle richieste tramite l’header Idempotency-Key. Questa pagina definisce il contratto HTTP; per la strategia dei tentativi successivi, consulta Idempotenza.

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.

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.

Le risposte 5xx non vengono mai memorizzate in cache. Riprova con backoff usando la stessa chiave e richiesta. E01033 IdempotencyUnavailable indica che questo tentativo non è stato eseguito; non descrive l'esito di un tentativo precedente. Mantieni la chiave a ogni retry.

Un'operazione può avere effetto prima che la sua risposta venga conservata. Se quella risposta viene persa, o il lock in-flight scade, un retry può eseguire di nuovo l'operazione. Un timeout o un'altra risposta 5xx non dimostrano quindi che l'operazione non abbia avuto effetto.

Gli SDK ufficiali allegano un UUID Idempotency-Key generato automaticamente a ogni richiesta mutante, creato una volta per chiamata logica e riutilizzato in tutti i tentativi di retry di quella chiamata. Puoi fornire la tua chiave per ogni chiamata (idempotencyKey in TypeScript, option.WithIdempotencyKey in Go, idempotency_key in Python) quando un'operazione logica coinvolge più chiamate SDK. Per rilevare un replay, 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.