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?
Sie setzen einen Idempotency-Key-Header für jeden beabsichtigten SMS-Sendevorgang und verwenden ihn beim erneuten Versuch des identischen Requests wieder. Wenn Bird die ursprüngliche Antwort gespeichert hat, gibt ein übereinstimmender erneuter Versuch diese Antwort zurück, ohne den Sendevorgang erneut auszuführen.
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.
409mitE01005 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.409mitE01004 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. Die In-Flight-Sperre läuft innerhalb von 30 Sekunden ab. Der Ablauf gibt keinen Aufschluss darüber, ob der ursprüngliche Sendevorgang gewirkt hat.503mitE01033 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. Bird speichert5xx-Antworten nicht. Ein erneuter Versuch spielt eine gespeicherte erfolgreiche Antwort ab oder kann erneut ausgeführt werden, wenn keine Antwort gespeichert wurde.
Der Idempotenz-Header bewahrt die Identität des Requests über diese erneuten Versuche hinweg.
Garantiert der Key, dass keine Duplikate entstehen?
Der Key reduziert doppelte Sendungen, garantiert aber keine einmalige Ausführung.
Ein Sendevorgang kann wirksam werden, bevor Bird seine Antwort speichert. Wenn die Speicherung der Antwort fehlschlägt oder die In-Flight-Sperre abläuft, kann ein erneuter Versuch den Sendevorgang erneut ausführen. Das Drei-Stunden-Speicherfenster begrenzt den Replay-Schutz ebenfalls.
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?
- Weisen Sie jedem beabsichtigten SMS-Sendevorgang einen Key zu und verwenden Sie den identischen Request bei erneuten Versuchen wieder.
- Versuchen Sie Netzwerkfehler, Timeouts und
5xx-Antworten mit Backoff erneut und behalten Sie den Key bei, um verfügbaren Replay-Schutz zu nutzen. - Beheben Sie Konflikte durch geänderte Requests und verzögern Sie erneute Versuche, solange der ursprüngliche Request noch läuft.
- Gleichen Sie unklare Sendungen ab, einschließlich solcher jenseits des Drei-Stunden-Replay-Fensters, bevor Sie entscheiden, ob ein erneuter Sendevorgang angemessen ist.
Kurz gesagt
Ein Key identifiziert einen beabsichtigten Sendevorgang.
Erneute Versuche verwenden denselben Key und Request wieder. Eine gespeicherte Antwort wird innerhalb von drei Stunden abgespielt.
Ein
409kann einen geänderten oder unvollständigen Request kennzeichnen.IdempotencyKeyReuse bedeutet, dass der Request sich geändert hat. RequestInProgress bedeutet, dass der ursprüngliche Request noch läuft und ein verzögerter erneuter Versuch nötig ist.
Nicht verfügbarer Schutz blockiert diesen Versuch.
Eine 503-IdempotencyUnavailable-Antwort bedeutet, dass dieser Versuch nicht ausgeführt wurde. Sie gibt keinen Aufschluss über das Ergebnis eines früheren Versuchs.
Antwort-Replay reduziert das Duplikat-Risiko, beseitigt es aber nicht.
Ein Sendevorgang kann wirksam werden, bevor seine Antwort gespeichert wird. Ein abgelaufener Replay-Eintrag erlaubt ebenfalls eine erneute Ausführung.