Bestell-Duplikate bei der API-Nutzung: Ursachen und Schutz

Warum Duplikate nach einer einzigen Aktion entstehen

Der Besitzer eines Panels kann einmal auf eine Schaltfläche klicken und mehrere identische Bestellungen sehen: für Abonnenten, Aufrufe, Reaktionen oder eine andere Leistung. Meist liegt das Problem nicht im Klick selbst, sondern in der Kette zwischen Client, API, Datenbank und Anbieter.

Aus Sicht des Servers ist „eine Anfrage“ nicht immer eine. Der Client hat möglicherweise keine Antwort erhalten, die Sendung wiederholt, während die erste Operation bereits gespeichert wurde. Manchmal wird die Bestellung einmal in der Datenbank des Panels angelegt, aber zweimal an den Anbieter gesendet. Das sind unterschiedliche Szenarien, und sie werden unterschiedlich behoben.

Ein Timeout bedeutet nicht, dass die Bestellung nicht erstellt wurde

Die häufigste Ursache ist, dass der Client nur eine begrenzte Zeit auf eine Antwort wartet. Der Server nimmt die Anfrage an, erstellt die Bestellung, antwortet aber später als das festgelegte Timeout. Der Client betrachtet die Operation als fehlgeschlagen und sendet sie erneut.

Infolgedessen ist die erste Bestellung bereits in der Datenbank, und die zweite Anfrage erstellt eine weitere. Besonders häufig passiert das bei einer langsamen Antwort der externen API, einer überlasteten Warteschlange oder einer instabilen Verbindung zwischen den Diensten.

Ein Timeout sagt nur, dass keine Antwort vorliegt, nicht dass die Anfrage nicht verarbeitet wurde.

Automatische Wiederholungen auf der Client-Seite

Bibliotheken für HTTP-Anfragen, Hintergrundaufgaben und Integrationsdienste wiederholen Anfragen nicht selten automatisch. Auslöser kann ein Verbindungsfehler, ein Server-Antwortcode, eine Netzwerkunterbrechung oder eine zu langsame Antwort sein.

Eine Wiederholung ist an sich nützlich: Sie verringert die Zahl verlorener Bestellungen bei vorübergehenden Störungen. Der Nachteil dieses Ansatzes ist, dass ohne Schutz vor erneuter Verarbeitung jede Netzwerkinstabilität in Duplikate umgewandelt wird.

• die Wiederholung kann im Code der Website oder des Bots ausgelöst werden;
• die Aufgabe kann von der Warteschlange neu gestartet werden;
• die Anfrage kann von einem Proxy oder einem Integrationsmodul wiederholt werden;
• der Bediener kann die Bestellung nach einem Fehler manuell erneut senden.

Eine wiederholte Anfrage kommt vor der ersten Antwort an

Manchmal erreichen zwei identische Anfragen die API tatsächlich nahezu gleichzeitig. Beispielsweise hat der Nutzer das Formular zweimal abgeschickt, das Frontend hat die Schaltfläche nicht gesperrt, oder eine Hintergrundaufgabe wurde vor Abschluss der ersten erneut gestartet.

Wenn der Handler zuerst das Vorhandensein der Bestellung prüft und sie dann erstellt, können zwei parallele Operationen die Prüfung gleichzeitig bestehen. Jede sieht, dass die Bestellung noch nicht existiert, und jede fügt einen neuen Datensatz hinzu.

Eine solche Situation nennt man Race Condition. Eine einfache Vorabprüfung im Code schützt nicht vollständig davor. Der Nachteil einer Prüfung ohne Einschränkung auf Datenbankebene ist, dass sie bei paralleler Last versagt.

Die Bestellung wurde gespeichert, aber die API-Antwort ging verloren

Die Anfrage durchläuft mehrere Phasen: Der Server empfängt die Daten, erstellt den Datensatz, stellt die Aufgabe in die Warteschlange, sendet die Antwort. Ein Fehler ist zwischen jeder dieser Phasen möglich. Beispielsweise hat die Datenbank die Erstellung der Bestellung bereits bestätigt, aber die Verbindung brach ab, bevor die Antwort an den Client übertragen wurde.

Der Client weiß nicht, ob die Bestellung angenommen wurde, und wiederholt die Operation. Eine API ohne einen separaten Prüfmechanismus betrachtet die Anfrage als neu. Im Protokoll sieht es oft so aus, als hätte der Dienst zwei Bestellungen „von selbst“ erstellt, obwohl bei ihm zwei eingehende Aufrufe vorlagen.

Idempotenzschlüssel für die Erstellung einer Bestellung

Für Erstellungsoperationen ist ein eindeutiger Idempotenzschlüssel erforderlich. Der Client generiert ihn vor dem ersten Senden und übergibt ihn zusammen mit den Bestellparametern. Bei einer Wiederholung aufgrund eines Timeouts oder Fehlers wird derselbe Schlüssel verwendet.

Die API speichert den Schlüssel zusammen mit dem Verarbeitungsergebnis. Wenn eine Anfrage mit einem bereits bekannten Schlüssel eintrifft, erstellt der Server keine neue Bestellung, sondern gibt das Ergebnis des ersten Aufrufs zurück: die Bestell-ID, ihren Status oder einen zuvor erzeugten Fehler.

Ein Schlüssel sollte einer Geschäftsoperation entsprechen, nicht einer HTTP-Verbindung.

Der Nachteil dieser Methode ist, dass Schlüssel gespeichert, nach Regeln bereinigt und auf der API-Seite geprüft werden müssen. Wenn bei jeder Wiederholung ein neuer Schlüssel generiert wird, greift der Schutz nicht. Wenn ein Schlüssel für verschiedene Bestellungen verwendet wird, werden einige neue Operationen fälschlicherweise abgelehnt.

Die Eindeutigkeit muss von der Datenbank kontrolliert werden

Idempotenz sollte besser durch eine Eindeutigkeitsbeschränkung in der Datenbank ergänzt werden. Dafür wählt man eine Kombination, die die Bestellung eindeutig beschreibt: interne Client-ID, Idempotenzschlüssel, Leistungsart und weitere erforderliche Felder.

Die Datenbank muss den zweiten Datensatz ablehnen, selbst wenn zwei Handler gleichzeitig zur Erstellung gelangt sind. Nach einem Konflikt gibt die API die bestehende Bestellung zurück, nicht einen Fehler ohne Erklärung.

Der Nachteil einer starren Eindeutigkeitsbeschränkung ist, dass sie nicht allein auf einem Link oder Benutzernamen aufgebaut werden darf. Ein Client kann bewusst dieselbe Leistung für denselben Kanal mehrmals bestellen. Eine zu breite Beschränkung blockiert normale Nachkäufe.

Eine Warteschlange kann eine Aufgabe mehr als einmal zustellen

Aufgabenwarteschlangen arbeiten häufig nach dem Prinzip „mindestens einmal zustellen“. Wenn ein Worker die Aufgabe verarbeitet, aber ihre Ausführung nicht rechtzeitig bestätigt hat, kann die Warteschlange dieselbe Aufgabe erneut an einen anderen Worker ausgeben.

Für die Warteschlange ist das eine normale Methode, um keine Aufgabe zu verlieren. Für die Erstellung einer Bestellung ohne Idempotenz ist es eine Quelle von Duplikaten. Die Aufgaben-ID oder ein separater Operationsschlüssel muss bis zum endgültigen Handler weitergegeben werden, einschließlich des Moduls, das die Bestellung an den Anbieter sendet.

Der Nachteil des Abschaltens der erneuten Zustellung ist, dass beim Ausfall eines Workers ein Teil der Bestellungen verloren gehen kann. Sicherer ist es, mögliche Wiederholungen zu akzeptieren und den Handler widerstandsfähig dagegen zu machen.

Duplikate entstehen zwischen Panel und Anbieter

Die interne Bestellung kann einmal erstellt, aber die Anfrage an die externe API zweimal gesendet worden sein. Die Ursache ist dieselbe: Das Panel hat keine Antwort vom Anbieter erhalten und beschlossen, die Sendung zu wiederholen. Wenn der Anbieter die erste Anfrage bereits angenommen hat, erscheinen auf seiner Seite zwei identische Anforderungen.

Es ist eine separate Verknüpfung der internen Bestellung mit der externen erforderlich: Sendungs-ID, Idempotenzschlüssel oder gespeicherte Antwort des Anbieters. Man darf nicht davon ausgehen, dass der Schutz am Eingang des eigenen Panels automatisch die ausgehenden Aufrufe schützt.

Der Nachteil des Abgleichs mit einer fremden API ist, dass nicht jeder Anbieter die Suche nach einem externen Schlüssel unterstützt. Dann müssen die Sendungsversuche festgehalten und unbestimmte Status separat geklärt werden.

Ein Webhook darf keine neue Bestellung erstellen

Webhooks melden Änderungen: Bestellung angenommen, gestartet, ausgeführt, storniert oder prüfungsbedürftig. Ein Fehler entsteht, wenn der Webhook-Handler die Benachrichtigung als Befehl auffasst, die Bestellung neu zu erstellen.

Derselbe Webhook kann erneut eintreffen. Der Absender wiederholt die Zustellung, wenn er keine Bestätigung erhalten hat, und Benachrichtigungen kommen manchmal nicht in der richtigen Reihenfolge an. Der Handler muss die bestehende Bestellung anhand der externen ID finden und den Status aktualisieren.

Der Nachteil der Verarbeitung von Webhooks nur nach Empfangszeit ist, dass eine späte Benachrichtigung den aktuellen Status mit einem veralteten überschreiben kann. Es sind eine Ereignis-ID, eine Statusversion oder klare Übergangsregeln erforderlich.

Welche Aufzeichnungen helfen, die Quelle von Duplikaten zu finden

Für die Untersuchung reicht es nicht, nur zwei Bestellnummern zu sehen. Es sind Daten zu jeder Verarbeitungsphase erforderlich: Anfragezeit, Idempotenzschlüssel, Client-ID, Bestellparameter, Nummer der Hintergrundaufgabe, Antwort der externen API und Versuche der erneuten Sendung.

• gleichen Sie Duplikate nach dem Operationsschlüssel ab, nicht nur nach dem Link;
• prüfen Sie, ob identische Anfragen im Protokoll der eingehenden API vorhanden waren;
• sehen Sie nach, ob die Aufgabe in der Warteschlange wiederholt wurde;
• trennen Sie die Erstellung der internen Bestellung von der Sendung an den Anbieter;
• speichern Sie die externe Anforderungs-ID sofort nach Erhalt der Antwort.

Der Nachteil zu kurzer Logs ist, dass die Problemquelle verschwindet, bevor sie geklärt werden kann. Der Nachteil übermäßiger Protokollierung ist, dass Tokens, personenbezogene Daten und andere sensible Felder in die Aufzeichnung gelangen können, weshalb sie maskiert werden müssen.

Wie ein unbestimmtes Anfrageergebnis behandelt wird

Nach einem Timeout darf die Bestellung nicht sofort mit neuen Daten erneut erstellt werden. Zuerst muss die API die Operation anhand des Idempotenzschlüssels oder der Client-ID prüfen. Wenn die Bestellung gefunden wird, wird ihr aktueller Zustand zurückgegeben. Wenn die Verarbeitung noch läuft, erhält der Client einen Wartestatus.

1. Den Operationsschlüssel vor der ersten Anfrage erstellen.
2. Bei jeder Wiederholung denselben Schlüssel senden.
3. Den Schlüssel und die Bestellung in einer einzigen abgesicherten Datenbankoperation speichern.
4. Die Operations-ID an die Warteschlange und die externe API weitergeben.
5. Bei erneutem Aufruf die zuvor erstellte Bestellung zurückgeben.

Ein solches Szenario erfordert Anpassungen an der API und der Client-Integration. Sein Nachteil ist die schwierigere Fehlersuche und die größere Zahl von Bestellzuständen, dafür bedeutet eine erneute Zustellung der Anfrage nicht mehr automatisch einen erneuten Kauf.