Wie vermeide ich, dieselbe SMS doppelt zu senden?

Eine Verbindung kann abbrechen, nachdem Bird einen SMS angenommen hat, aber bevor Ihre Anwendung die Antwort empfängt. Ein erneuter Versuch mit einem neuen Key kann einen doppelten Versand erzeugen, weil Bird ihn als separaten Request behandelt.

Wie funktioniert der Key?

Setzen Sie für jeden beabsichtigten SMS-Sendevorgang einen Idempotency-Key-Header und verwenden Sie ihn wieder, wenn Sie den identischen Request erneut versuchen. Die Garantie der genau einmaligen Annahme bedeutet, dass übereinstimmende erneute Versuche innerhalb von drei Stunden zum selben angenommenen Sendevorgang führen müssen, auch wenn Ihnen dessen Antwort verloren gegangen ist.

Zum Beispiel behält eine Bestellbestätigung denselben Key über ein Timeout und den erneuten Versuch hinweg. Eine Bestätigung für eine andere Bestellung erhält einen anderen Key.

Abgespielte Antworten enthalten Idempotency-Replay: true, sodass Ihre Logs ein Replay von einem neu verarbeiteten Request unterscheiden können.

SMS-Keys sind auf Ihren Workspace beschränkt. Bird speichert abgeschlossene Antworten drei Stunden lang gemäß seinem Idempotenz-Vertrag. Nach diesem Zeitfenster kann derselbe Key einen neuen Request ausführen, weil sein Replay-Eintrag abgelaufen ist. Ein erneuter Versuch einen Tag später erfordert daher eine Abgleichung des ursprünglichen Ergebnisses, bevor erneut gesendet wird.

Was sagen mir die Fehlerantworten?

Der Fehlercode unterscheidet einen geänderten Request, einen unvollständigen Request und nicht verfügbaren Schutz.

• 409 mit E01005 IdempotencyKeyReuse: Derselbe Key wurde für einen anderen Request verwendet. Korrigieren Sie die Key-Zuordnung, bevor Sie es erneut versuchen, da dieser Key zum ursprünglichen Request gehört. Bird vergleicht Methode, Endpunkt, Pfad- und Query-Parameter sowie den rohen Body. Selbst eine JSON-Änderung an Leerzeichen macht den Request zu einem anderen.
• 409 mit E01004 RequestInProgress: Ein gleichzeitiger Request mit demselben Key ist noch nicht abgeschlossen. Warten Sie kurz und versuchen Sie es mit demselben Key und Request erneut, damit der ursprüngliche Request abgeschlossen werden kann.
• 503 mit E01033 IdempotencyUnavailable: Der Schutz war vor der Ausführung nicht verfügbar, daher wurde dieser Versuch nicht ausgeführt. Versuchen Sie es mit Backoff unter Verwendung desselben Keys und Requests erneut. Diese Antwort gibt keinen Aufschluss über das Ergebnis eines früheren Versuchs.
• Andere 5xx-Antworten oder Timeouts: Versuchen Sie es mit Backoff unter Verwendung desselben Keys und Requests erneut. Die Garantie der genau einmaligen Annahme gilt für diese erneuten Versuche innerhalb von drei Stunden. Hören Sie auf, wenn Ihr Budget für erneute Versuche ausgeschöpft ist.

Der Idempotenz-Header bewahrt die Identität des Requests über diese erneuten Versuche hinweg.

Garantiert der Key, dass keine Duplikate entstehen?

Die Garantie ist eine genau einmalige Annahme identischer Requests mit demselben Key im selben Workspace innerhalb von drei Stunden. Diese erneuten Versuche müssen zu einem einzigen angenommenen Sendevorgang führen, auch nach einer verlorenen Antwort. Prüfen Sie den Nachrichtenstatus, um die Zustellung zu bestätigen.

Nach dem dreistündigen Aufbewahrungsfenster kann der ursprüngliche Key einen neuen Vorgang kennzeichnen. Gleichen Sie ein unbekanntes ursprüngliches Ergebnis ab, bevor Sie erneut senden.

Führen Sie Ihre eigenen Ereignis- und Sendeaufzeichnungen, damit Sie ein unklares Ergebnis abgleichen können, bevor Sie erneut senden. Fügen Sie die Bestell- oder Referenznummer in die Nachricht ein, damit der Empfänger erkennen kann, welches Ereignis sie betrifft.

Was ist mit einer Nachricht, die das Gerät doppelt anzeigt?

Ein Idempotency-Key steuert erneute API-Versuche; er kontrolliert nicht, wie das Telefon des Empfängers eine Nachricht anzeigt. Ein Screenshot allein gibt keinen Aufschluss darüber, wo ein Duplikat entstanden ist.

Vergleichen Sie das vollständige Sendelog Ihrer Anwendung mit den Nachrichtendatensätzen von Bird. Mehrere akzeptierte Message-IDs können mehrere Sendungen belegen. Eine einzige ID in einem unvollständigen Log beweist nicht, dass das Duplikat downstream entstanden ist. Geben Sie die relevanten IDs, das Ziel und die Zeitstempel an, wenn Sie den Support um Untersuchung bitten.

Was sollte ich tun?

1. Weisen Sie jedem beabsichtigten SMS-Sendevorgang einen Key zu und verwenden Sie den identischen Request bei erneuten Versuchen wieder.
2. Versuchen Sie Netzwerkfehler, Timeouts und 5xx-Antworten mit Backoff erneut und behalten Sie innerhalb von drei Stunden den Key und den identischen Request bei.
3. Beheben Sie Konflikte durch geänderte Requests und verzögern Sie erneute Versuche, solange der ursprüngliche Request noch läuft.
4. Behandeln Sie ausgeschöpfte oder abgelaufene erneute Versuche als ungeklärt, bis Sie ihr Ergebnis abgeglichen haben, bevor Sie entscheiden, ob ein weiterer Sendevorgang angemessen ist.