Idempotency-Key-Header

Die Bird API unterstützt optionale Deduplizierung von Anfragen über den Idempotency-Key-Header. Diese Seite beschreibt den Wire-Contract; für die Konzepte (Warum, Wann und Retry-Strategie) siehe Idempotenz.

Workspace- und organisationsbezogene Mutationen unterstützen dieses Response-Replay. Rein nutzerbezogene und nicht authentifizierte Operationen, Streams und Operationen mit einem eigenen Replay-Contract umgehen es. Einen Key an eine Operation zu senden, die das Replay umgeht, bietet keinen Deduplizierungsschutz.

Wird der Header weggelassen, wird die Idempotenz vollständig übersprungen: Die Anfrage wird normal ohne Deduplizierung verarbeitet. Ein leerer Key oder einer mit mehr als 255 Zeichen liefert 400 mit dem Code E01002 InvalidRequest zurück.

Keys sind auf Ihren Workspace beschränkt und werden etwa 3 Stunden aufbewahrt. Nach Ablauf des Aufbewahrungsfensters wird ein wiederverwendeter Key als neue Anfrage verarbeitet.

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "from": "hello@yourdomain.com", "to": ["delivered@messagebird.dev"], "subject": "Welcome!", "html": "<p>Hi.</p>" }'

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 Query-Parameter sowie den unveränderten Request-Body; jeder Unterschied, auch Leerzeichen, macht es zu einer anderen Anfrage und löst E01005 aus. Beide 409-Fehler werden in der Standard-Fehlerantwort gekapselt.

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.