Idempotenz
Netzwerke fallen im ungünstigsten Moment aus: Sie senden einen POST, die Verbindung bricht ab, und Sie wissen nicht, ob die E-Mail rausgegangen ist. Idempotenz ermöglicht es Ihnen, diesen Request sicher zu wiederholen. Senden Sie denselben Idempotency-Key-Header erneut, und Bird gibt die ursprüngliche Antwort zurück, anstatt den Request ein zweites Mal zu verarbeiten.
So funktioniert es
Idempotenz ist opt-in. Fügen Sie einem unterstützten POST-, PATCH-, PUT- oder DELETE-Request einen Idempotency-Key-Header hinzu. Requests ohne diesen Header werden normal ohne Deduplizierung verarbeitet. GET-Requests ignorieren den Header.
Auf der Customer-API unterstützen Workspace- und organisationsbezogene Mutationen das unten beschriebene Response-Replay. Rein nutzerbezogene und nicht zugeordnete, nicht authentifizierte Operationen sowie Streams umgehen es. Operationen mit einem eigenen Replay-Vertrag definieren ihr Verhalten auf ihrer Referenzseite. Zum Beispiel behält Sprachanruf erstellen den ursprünglichen Akzeptanz-Snapshot für übereinstimmende Wiederholungen bei, wenn Sie einen Key angeben.
Die SDKs generieren für jeden mutierenden Aufruf einen Key und verwenden ihn bei automatischen Wiederholungen wieder, einschließlich der Anruferstellung. Für automatische SDK-Wiederholungen müssen Sie keinen eigenen angeben. Geben Sie einen eigenen Key an, wenn eine beabsichtigte Operation mehrere separate SDK-Aufrufe umfasst, etwa eine Wiederholung nach einem Neustart Ihrer Anwendung. Diese Beispiele zeigen diesen Fall.
await bird.email.send(
{
from: "hello@yourdomain.com",
to: ["delivered@messagebird.dev"],
subject: "Welcome!",
html: "<p>Thanks for signing up.</p>",
},
{ idempotencyKey: "welcome-user/usr_abc123" },
);client.email.send(
from_="hello@yourdomain.com",
to=["delivered@messagebird.dev"],
subject="Welcome!",
html="<p>Thanks for signing up.</p>",
options={"idempotency_key": "welcome-user/usr_abc123"},
)_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
From: "hello@yourdomain.com",
To: []string{"delivered@messagebird.dev"},
Subject: "Welcome!",
HTML: "<p>Thanks for signing up.</p>",
}, option.WithIdempotencyKey("welcome-user/usr_abc123"))$bird->email->send(
from: 'hello@yourdomain.com',
to: ['delivered@messagebird.dev'],
subject: 'Welcome!',
html: '<p>Thanks for signing up.</p>',
options: new RequestOptions(idempotencyKey: 'welcome-user/usr_abc123'),
);curl -X POST https://us1.platform.bird.com/v1/email/messages \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: welcome-user/usr_abc123" \
-d '{
"from": "hello@yourdomain.com",
"to": ["delivered@messagebird.dev"],
"subject": "Welcome!",
"html": "<p>Thanks for signing up.</p>"
}'Ein Key ist ein beliebiger nicht leerer String mit bis zu 255 Zeichen. Ein leerer Header-Wert überspringt die Deduplizierung. Das empfohlene Format ist ein deterministischer Key, der aus Ihren eigenen Entitäten abgeleitet wird, <event-type>/<entity-id> (zum Beispiel welcome-user/usr_abc123), sodass Wiederholungen über Prozessneustarts hinweg denselben Key verwenden; eine zufällige UUID pro logischer Operation funktioniert ebenfalls. Die Bird-SDKs generieren automatisch einen UUID-Key für jeden mutierenden Request und verwenden ihn bei ihren internen Wiederholungen wieder.
Keys sind auf Ihren Workspace beschränkt, oder auf Ihre Organisation bei Endpunkten auf Organisationsebene. Eine abgeschlossene Antwort wird 3 Stunden aufbewahrt; eine Wiederholung nach diesem Zeitfenster wird als neuer Request verarbeitet. Das Zeitfenster deckt übliche Wiederholungsintervalle ab. Nach Ablauf bleibt kein Deduplizierungseintrag bestehen.
Replays
Wenn Bird einen Key erkennt, der bereits abgeschlossen wurde, gibt es die zwischengespeicherte Antwort zurück – gleicher Statuscode, gleicher Body – ohne den Request erneut auszuführen. Wiederholte Antworten enthalten einen zusätzlichen Header, damit Sie sie von einer neuen Verarbeitung unterscheiden können:
Codebeispiel
HTTP/1.1 202 Accepted
Idempotency-Replay: trueAufbewahrte Antworten können 4xx-Ablehnungen enthalten. Verwenden Sie einen neuen Key, wenn Sie einen Request korrigieren: Wurde die Ablehnung aufbewahrt, gibt eine unveränderte Wiederholung sie erneut zurück, und ein geänderter Request liefert 409 E01005 IdempotencyKeyReuse. 5xx-Antworten werden nicht aufbewahrt, wiederholen Sie sie daher mit demselben Key und Request.
Fehlerfälle
| Szenario | Antwort |
|---|---|
| Gleicher Key, gleicher Request, Original abgeschlossen | Zwischengespeicherte Antwort wiedergegeben mit Idempotency-Replay: true |
| Gleicher Key, anderer Request-Body oder Endpunkt | 409, E01005 IdempotencyKeyReuse |
| Gleicher Key, ursprünglicher Request noch in Verarbeitung | 409, E01004 RequestInProgress |
| Key länger als 255 Zeichen an einem Endpunkt, der den Header deklariert | 422, E01001 ValidationError |
| Idempotenz-Schutz vor Ausführung nicht verfügbar | 503, E01033 IdempotencyUnavailable; dieser Versuch wird nicht ausgeführt |
Die Wiederverwendung eines abgeschlossenen Keys mit einem anderen Request wird als Client-Fehler behandelt: Bird gibt sofort 409 zurück, anstatt Ihnen stillschweigend eine Antwort zu liefern, die nicht zu dem passt, was Sie gesendet haben. Generieren Sie einen neuen Key für den neuen Request. Der Vergleich umfasst Methode, Endpunkt, Pfad- und Query-Parameter sowie den rohen Request-Body, einschließlich JSON-Whitespace. Multipart-Uploads vergleichen Part-Namen, Dateinamen und Inhalte; Boundaries und Part-Reihenfolge haben keinen Einfluss auf das Replay.
RequestInProgress bedeutet, dass ein gleichzeitiger Request mit demselben Key noch nicht abgeschlossen ist – typischerweise ein aggressives clientseitiges Timeout, das wiederholt, während der erste Versuch noch verarbeitet wird. Die In-Flight-Sperre läuft innerhalb von 30 Sekunden ab, warten Sie also kurz und versuchen Sie es erneut. Siehe Fehler für die Fehlerantwort, in der diese zurückgeliefert werden.
Was nicht zwischengespeichert wird
5xx-Antworten werden nie zwischengespeichert. Der Key wird freigegeben, und Bird kann eine Wiederholung als neuen Versuch verarbeiten. Wiederholen Sie 5xx-Antworten und Timeouts mit Backoff unter Verwendung desselben Keys und Requests. Eine Operation kann wirksam werden, bevor ihre Antwort aufbewahrt wird; geht diese Antwort verloren oder läuft die In-Flight-Sperre ab, kann eine Wiederholung die Operation erneut ausführen.
Wenn der Idempotenz-Schutz vor der Ausführung nicht verfügbar ist, gibt API 503 E01033 IdempotencyUnavailable zurück, ohne diesen Versuch auszuführen. Behalten Sie den Key bei jeder Wiederholung bei. Dieser Fehler beschreibt nicht das Ergebnis eines früheren Versuchs mit demselben Key.
Praktische Hinweise
- Generieren Sie einen Key pro logischer Operation und verwenden Sie ihn für jeden HTTP-Versuch dieser Operation wieder.
- Wiederholen Sie bei Netzwerkfehlern, Timeouts und 5xx mit exponentiellem Backoff und verwenden Sie jedes Mal denselben Key.
- Behandeln Sie 409 IdempotencyKeyReuse als Fehler in Ihrer Key-Generierung. Wiederholen Sie ihn nicht.
- Keys sind bei Mutationen optional. Verwenden Sie einen, wenn Sie Wiederholungsschutz benötigen; lassen Sie ihn bei GET-Requests weg.
Nächste Schritte
- Idempotenz-API-Referenz: Header- und Response-Header-Schemas
- SDK-Konzepte: automatische Key-Generierung und Wiederholungsverhalten in den SDKs
- Fehler: die Fehlerantwort und der Fehlerkatalog
- E-Mail senden: Send- und Batch-Endpunkte
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.