Idempotenz

Verwenden Sie Idempotency-Key, wenn Sie nach einer abgebrochenen Verbindung nicht wissen, ob Ihr Request erfolgreich war. Die Garantie lautet genau einmalige Annahme: Erneute Versuche mit demselben Key und identischem Request müssen innerhalb des 3-stündigen Aufbewahrungszeitfensters zu einer einzigen angenommenen Operation führen, auch wenn die ursprüngliche Antwort verloren gegangen ist.

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 erneute Versuche bei, wenn Sie einen Key angeben.

Die SDKs generieren für jeden mutierenden Aufruf einen Key und verwenden ihn bei automatischen erneuten Versuchen wieder, einschließlich der Anruferstellung. Für automatische erneute SDK-Versuche müssen Sie keinen eigenen Key angeben. Geben Sie einen eigenen Key an, wenn eine beabsichtigte Operation mehrere separate SDK-Aufrufe umfasst, etwa wenn Sie es nach einem Neustart Ihrer Anwendung erneut versuchen. 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 erneute Versuche ü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 erneuten Versuchen wieder.

Keys gelten für Ihren Workspace bzw. bei Endpunkten auf Organisationsebene für Ihre Organisation. Eine abgeschlossene Antwort wird 3 Stunden aufbewahrt; ein erneuter Versuch nach diesem Zeitfenster kann als neuer Request verarbeitet werden. Ist das Ergebnis der ursprünglichen Operation nach Ablauf unbekannt, behandeln Sie sie weiterhin als ungeklärt und gleichen Sie ihren Status ab, bevor Sie erneut senden.

Replays

Ein übereinstimmender erneuter Versuch innerhalb von drei Stunden muss zur ursprünglichen Operation führen. Ist deren Antwort aufbewahrt, gibt API denselben Statuscode und Body zurück, ohne eine weitere Operation anzunehmen. Wiedergegebene Antworten enthalten einen zusätzlichen Header, damit Sie sie von einer neuen Verarbeitung unterscheiden können:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

Aufbewahrte Antworten können 4xx-Ablehnungen enthalten. Verwenden Sie einen neuen Key, wenn Sie einen Request korrigieren: Wurde die Ablehnung aufbewahrt, gibt ein unveränderter erneuter Versuch sie erneut zurück, und ein geänderter Request liefert 409 E01005 IdempotencyKeyReuse. 5xx-Antworten werden nicht als abgeschlossene Antworten aufbewahrt. Die Garantie der genau einmaligen Annahme gilt auch für erneute Versuche nach diesen Fehlern.

Fehlerfälle

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 wiederholt ein aggressives clientseitiges Timeout den Request, während der erste Versuch noch verarbeitet wird. Warten Sie kurz und wiederholen Sie den Request mit demselben Key und identischem Inhalt. Unter Fehler finden Sie die Fehlerantwort, in der diese Fehler zurückgegeben werden.

Was nicht zwischengespeichert wird

5xx-Antworten werden nicht als abgeschlossene Antworten aufbewahrt. Wiederholen Sie den Request innerhalb von drei Stunden mit begrenztem Backoff, demselben Key und identischem Request. Die Garantie der genau einmaligen Annahme gilt auch dann, wenn die ursprüngliche Antwort verloren gegangen ist.

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 jedem erneuten Versuch 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 Requests bei Netzwerkfehlern, Timeouts und 5xx innerhalb von drei Stunden mit begrenztem exponentiellem Backoff, und behalten Sie dabei den Key und den identischen Request bei.
• Lassen Sie ein unbekanntes Ergebnis offen, wenn die Wiederholungen ausgeschöpft sind oder die Aufbewahrung abgelaufen ist. Gleichen Sie den Stand ab, bevor Sie eine weitere Operation mit dem alten oder einem neuen Key senden.
• Prüfen Sie bei Nachrichtenversand nach der Annahme den Nachrichtenstatus, um die Zustellung zu bestätigen.
• Behandeln Sie 409 IdempotencyKeyReuse als Fehler in Ihrer Key-Generierung. Versuchen Sie den Request nicht erneut.
• Keys sind bei Mutationen optional. Verwenden Sie einen, wenn Sie Schutz für erneute Versuche 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 das Verhalten bei erneuten Versuchen in den SDKs
• Fehler: die Fehlerantwort und der Fehlerkatalog
• E-Mail senden: Send- und Batch-Endpunkte