Idempotency-Key-Header

Die Bird API unterstützt eine optionale Deduplizierung von Anfragen über den Header Idempotency-Key. Diese Seite beschreibt das Verhalten auf HTTP-Ebene. Hinweise zu Wiederholungsversuchen finden Sie unter Idempotenz.

Mutationen im Geltungsbereich eines Workspace oder einer Organisation unterstützen die unten beschriebene Wiedergabe gespeicherter Antworten. Operationen, die ausschließlich einem Benutzer zugeordnet sind, nicht authentifizierte Operationen ohne Geltungsbereich und Streams nutzen sie nicht. Operationen mit einem eigenen Wiedergabevertrag beschreiben ihr Verhalten auf ihrer Referenzseite.

Wenn Sie den Header weglassen oder einen leeren Wert senden, wird die Anfrage normal und ohne Deduplizierung verarbeitet. Bei Endpunkten, die diesen Header deklarieren, führt ein Schlüssel mit mehr als 255 Zeichen zu 422 mit dem Code E01001 ValidationError.

Schlüssel gelten für Ihren Workspace oder bei Endpunkten auf Organisationsebene für Ihre Organisation und werden ungefähr 3 Stunden gespeichert. Nach Ablauf dieses Zeitraums wird eine Anfrage mit einem erneut verwendeten Schlüssel als neue Anfrage verarbeitet.

Eine wiedergegebene Response ist Byte für Byte das Original (gleicher Statuscode, gleicher Body), unterschieden nur durch den zusätzlichen Header:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

"Identical request" umfasst Methode, Endpunkt, Pfad- und Abfrageparameter sowie den unveränderten Anfrageinhalt. Unterschiede in diesen Werten, einschließlich Leerraum in JSON, lösen E01005 aus. Bei Multipart-Uploads werden Teilnamen, Dateinamen und Inhalte verglichen; Grenzen und Reihenfolge der Teile beeinflussen die Wiedergabe nicht. Beide 409-Fehler werden im Standardformat der Fehlerantwort zurückgegeben.

Gespeicherte Antworten können 4xx-Ablehnungen enthalten. Verwenden Sie beim Korrigieren einer Anfrage einen neuen Schlüssel: Wurde die Ablehnung gespeichert, gibt ein unveränderter Wiederholungsversuch sie erneut zurück; eine geänderte Anfrage führt zu 409 E01005 IdempotencyKeyReuse.

5xx-Responses werden nie zwischengespeichert. Wiederholen Sie mit Backoff unter Verwendung des selben Keys und derselben Anfrage. E01033 IdempotencyUnavailable bedeutet, dass dieser Versuch nicht ausgeführt wurde; es beschreibt nicht das Ergebnis eines früheren Versuchs. Behalten Sie den Key bei jedem Retry bei.

Eine Operation kann wirksam werden, bevor ihre Response gespeichert wird. Geht diese Response verloren oder läuft die In-Flight-Sperre ab, kann ein Retry die Operation erneut ausführen. Ein Timeout oder eine weitere 5xx-Response beweist daher nicht, dass die Operation keine Wirkung hatte.

Die offiziellen SDKs hängen an jede mutierende Anfrage eine automatisch generierte UUID Idempotency-Key an, die einmal pro logischem Aufruf erzeugt und über alle Retry-Versuche dieses Aufrufs wiederverwendet wird. Sie können pro Aufruf einen eigenen Key angeben (idempotencyKey in TypeScript, option.WithIdempotencyKey in Go, idempotency_key in Python), wenn eine logische Operation mehrere SDK-Aufrufe umfasst. Um ein Replay zu erkennen, lesen Sie den Idempotency-Replay-Response-Header über den Transport-Metadata-Accessor jedes SDK: .withResponse() in TypeScript, option.WithResponseInto in Go und with_raw_response in Python.