Wiederholungen, Limits und Duplikate in KI-APIs: So verhindern Sie, dass ein Fehler eine Aktion zweimal ausführt

Das Problem: Eine verlorene Antwort ist nicht gleichbedeutend mit einer fehlgeschlagenen Operation

In einer Integration mit einer KI-API beschreibt ein Timeout meist nur einen begrenzten Sachverhalt: Der Client hat innerhalb der konfigurierten Frist keine Antwort erhalten. Daraus lässt sich nicht allein ableiten, dass der Anbieter die Anfrage nicht empfangen, nicht verarbeitet oder keine nachgelagerte Aktion begonnen hat. Die Verbindung kann abbrechen, nachdem der Server die Anfrage akzeptiert hat; die Antwort kann verloren gehen, nachdem die Operation abgeschlossen ist; und ein lokaler Prozess kann neu starten, obwohl das Ergebnis außerhalb dieses Prozesses bereits existiert.

Dieser Unterschied wird besonders wichtig, wenn eine Modellausgabe operative Effekte auslöst. Das Wiederholen einer Textgenerierung kann eine andere Antwort erzeugen und Ressourcen verbrauchen, verändert aber normalerweise kein Geschäftssystem. Das Wiederholen einer Anweisung, die eine E-Mail versendet, eine Reservierung erstellt, eine Zahlung erfasst, eine Akte ändert oder ein Tool aufruft, kann hingegen einen doppelten Effekt verursachen. Die Sicherheit des Ablaufs darf weder davon abhängen, dass das Modell denselben Text zurückgibt, noch davon, dass ein einzelner Netzaufruf immer erfolgreich ankommt.

Die HTTP-Semantik hilft, die Problemgrenze festzulegen: Eine idempotente Anfrage ist eine Anfrage, deren beabsichtigter Effekt auf dem Server gleichwertig bleibt, auch wenn sie mehrmals ausgeführt wird. Das bedeutet nicht, dass jede Wiederholung kostenlos ist, die Antwort identisch bleibt oder keine zusätzlichen Protokolleinträge entstehen. Es bedeutet, dass sich der relevante Effekt wiederholt anwenden lassen muss, ohne das erwartete Endergebnis zu verändern. In KI-Abläufen muss diese Eigenschaft sowohl beim Aufruf des Anbieters als auch unabhängig davon in jedem externen System geprüft werden, das eine Aktion empfängt.

Ein mentales Modell: Anfrage, logische Operation, Versuch, Effekt und Bestätigung

Es ist sinnvoll, fünf Konzepte zu trennen, die häufig vermischt werden. Die logische Operation ist die geschäftliche Absicht, etwa „eine strukturierte Antwort für Vorgang X erzeugen“ oder „genau eine Freigabebenachrichtigung senden“. Die Anfrage ist eine konkrete Nachricht an eine API. Ein Versuch ist jede Übermittlung dieser Anfrage, einschließlich des ersten Aufrufs und seiner Wiederholungen. Der externe Effekt ist die beobachtbare Änderung in einem Zielsystem: eine versendete Nachricht, eine erstellte Zeile oder ein bestätigter Kauf. Die Bestätigung ist der Nachweis, mit dem die logische Operation als abgeschlossen, abgelehnt oder überprüfungsbedürftig markiert werden kann.

Eine einzige Operations-ID muss alle Versuche verbinden, die dieselbe Absicht verfolgen. Sie muss vor dem ersten Aufruf erzeugt und außerhalb des Prozessspeichers persistiert werden, damit sie Abstürze, Deployments und Hintergrundjobs übersteht. Verwenden Sie nicht ausschließlich eine vom Anbieter zurückgegebene Anfrage-ID als Identität: Bei einem frühen Fehler kann sie fehlen, und selbst wenn sie vorhanden ist, kennzeichnet sie üblicherweise einen Versuch, nicht die gesamte geschäftliche Absicht.

Zusätzlich zur Operations-ID sollten Sie für jeden Empfänger, der dies unterstützt, einen stabilen Idempotenzschlüssel speichern. Der Schlüssel muss bei der Wiederholung derselben logischen Operation gleich bleiben und sich ändern, wenn sich die Absicht ändert. Einen neuen Schlüssel bei jedem Wiederholungsversuch zu erzeugen, hebt die Deduplizierung auf. Einen Schlüssel für zwei verschiedene Operationen wiederzuverwenden, kann dazu führen, dass eine legitime Aktion mit einer Wiederholung verwechselt wird. Das Protokoll sollte die Beziehung zwischen Operation, Versuch, Ziel, verwendetem Schlüssel und beobachtetem Ergebnis festhalten.

Klassifizieren Sie das Risiko, bevor Sie Wiederholungen automatisieren

Es gibt keine einzige Richtlinie, die für alle Aufrufe geeignet ist. Die Einordnung einer Operation nach ihrem Wiederholungsrisiko zwingt dazu, festzulegen, was geschützt werden soll. Lesevorgänge oder Abfragen ohne Effekte lassen Wiederholungen häufig zu, wenn Kosten und Last kontrolliert werden. Textgenerierung ohne externe Effekte kann wiederholt werden, doch das Ergebnis kann abweichen; die Anwendung muss daher entscheiden, ob sie eine neue Ausgabe akzeptiert, eine Teilantwort behält oder den Fall als offen darstellt.

Ein idempotenter Schreibvorgang kann wiederholbar sein, wenn das Ziel garantiert, dass derselbe Schlüssel dieselbe Operation repräsentiert. Ein kompensierbarer Schreibvorgang kann später eine Rückgängigmachung erfordern, aber die Kompensation macht die Wiederholung nicht automatisch sicher: Auch sie kann fehlschlagen, verspätet eintreffen oder eigene Effekte haben. Irreversible oder schwer überprüfbare Aktionen brauchen eine höhere Schutzschwelle, etwa menschliche Bestätigung, eine vorherige Reservierung oder eine zuverlässige Abfrage des Zielsystems vor der Ausführung.

Diese Klassifizierung muss für den gesamten Ablauf gelten, nicht nur für den Modellaufruf. Ein Modell kann einen Tool-Aufruf korrekt erzeugen, obwohl das Tool bereits ausgeführt wurde, bevor dessen Antwort verloren ging. Die nachfolgende Textausgabe ist kein ausreichender Nachweis dafür, dass der Effekt genau einmal eingetreten ist. Die Ebene, die Tools ausführt, muss die Aktion mit eigenen Kontrollen protokollieren und deduplizieren.

Entwerfen Sie Idempotenz an zwei Grenzen

Die Deduplizierung eines Anbieteraufrufs und die Deduplizierung eines Geschäftseffekts sind verwandte, aber nicht gleichwertige Probleme. Selbst wenn eine Modell-API einen Idempotenzschlüssel akzeptiert, beweist dieser Schutz nicht, dass ein nachgelagertes Tool, ein E-Mail-Anbieter oder ein Zahlungssystem seinen Effekt nur einmal angewendet hat. Umgekehrt beseitigt ein idempotentes Tool weder die Kosten noch die Überlastung durch unnötig wiederholte Inferenzanfragen.

Robust ist ein Entwurf mit zwei Grenzen. An der ersten protokolliert der API-Wrapper die Operation und ordnet Versuche einem stabilen Schlüssel zu, sofern der Vertrag des Anbieters dies unterstützt. An der zweiten verwendet der Executor externer Aktionen eine eigene Effekt-ID und einen dauerhaften Deduplizierungsspeicher. Vor der Ausführung prüft er, ob für diese Operation bereits eine abgeschlossene Aktion vorliegt; falls ja, liefert er das bestehende Ergebnis zurück. Falls nicht, registriert er den Beginn so, dass eine spätere Untersuchung nach einem Neustart möglich bleibt.

Erfinden Sie keine Abgleichsfunktionen, die der tatsächliche Vertrag nicht anbietet. Die verfügbaren Quellen beschreiben allgemeine Wiederholungspraktiken und HTTP-Semantik, dokumentieren aber weder für jede KI-API eine universelle Statusabfrage für Operationen noch einen Idempotenzschlüssel, der für alle Endpunkte gilt. Prüfen Sie die Vertragsdokumentation des konkreten Endpunkts, bevor Sie sich auf eine dieser Funktionen verlassen.

Wiederholungsrichtlinie: Budget, Backoff und Jitter

Eine sichere Richtlinie setzt Grenzen, bevor ein Fehler eintritt. Sie muss festlegen, welche Fehlerfamilien für Wiederholungen infrage kommen, wie viele Versuche maximal zulässig sind, welche globale Deadline für die Operation gilt, welche maximale Wartezeit akzeptabel ist und welche Höchstkosten tragbar sind. Die Zahl der Versuche allein reicht nicht: Fünf Wiederholungen können die Nutzerfrist überschreiten, ein Kontingent verbrauchen oder Worker belegen, die Kapazität freigeben sollten.

Antworten zur Ratenbegrenzung und vorübergehende Serverfehler können eine Wartezeit und einen erneuten Versuch rechtfertigen, sofern die Operation wiederholbar ist und Budget verbleibt. Die OpenClaw-Dokumentation weist darauf hin, dass bestimmte auf Stainless basierende SDKs die Antworten 408, 409, 429 und die 5xx-Familie als wiederholbar behandeln können. Das beschreibt eine SDK-Richtlinie in diesem Kontext und keine universelle Regel für jeden Endpunkt oder externen Effekt. Fehler, die auf eine ungültige Anfrage, fehlende Autorisierung oder eine geschäftliche Bedingung hinweisen, werden nicht dadurch behoben, dass identische Daten erneut gesendet werden; die Ursache muss korrigiert oder der Ablauf angehalten werden.

Verwenden Sie exponentiellen Backoff, um das Intervall schrittweise zu vergrößern, und Jitter, damit viele Clients nicht gleichzeitig erneut versuchen. AWS empfiehlt sowohl exponentiellen Backoff als auch zufällige Streuung, außerdem begrenzte Wiederholungen und die Prüfung der Idempotenz vor einer Wiederholung. Wenn eine Antwort über ein Wiederholungssignal angibt, wie lange gewartet werden soll, respektieren Sie es, sofern es gültig und mit der Operations-Deadline vereinbar ist. Überschreitet die Wartezeit das Budget, dokumentieren Sie den Grund für Verschiebung oder Fehlschlag, statt unbegrenzt weiter zu warten.

Ratenlimits und Überlastung: Auch die Wiederholung ist Last

Ein Fehler 429 bedeutet, dass die verfügbare Kapazität oder das geltende Limit zu diesem Zeitpunkt keine Fortsetzung zulässt; er beweist nicht, dass mehr Druck das Problem löst. Eine sofortige Wiederholung kann einen begrenzten Vorfall in einen Traffic-Sturm verwandeln. Außerdem können fehlgeschlagene Versuche in Ratenlimits mitgezählt werden, sodass eine aggressive Strategie gültige Operationen noch weiter verzögert.

Steuern Sie die Nebenläufigkeit in der Arbeitswarteschlange, nicht nur in jedem einzelnen Client. Legen Sie gegebenenfalls Grenzen pro Anbieter, Modell, Zugangsdaten und Operationstyp fest. Reservieren Sie Kapazität für den Abgleich mehrdeutiger Zustände und für prioritäre Operationen; andernfalls kann eine Welle von Wiederholungen das System daran hindern, überhaupt festzustellen, was geschehen ist. Das Budget muss Wartezeit in der Queue, Verbindungszeit, Verarbeitungszeit und Pausen zwischen Versuchen einschließen.

Die OpenAI-Anleitung zu 429-Fehlern empfiehlt exponentiellen Backoff mit Jitter, wenn kein verwertbarer Wartehinweis vorliegt, und rät dazu, sowohl die Zahl der Wiederholungen als auch die insgesamt dafür aufgewendete Zeit zu begrenzen. Wichtig ist, eine vorübergehende Begrenzung von anderen Konto- oder Kontingentproblemen zu unterscheiden, die sich nicht durch Warten lösen lassen. Die Entscheidung muss sich auf die Fehlerinformationen und den Integrationsvertrag stützen, nicht nur auf den Statuscode.

Mehrdeutige Zustände: Vor der Wiederholung abgleichen

Ein mehrdeutiger Zustand liegt vor, wenn keine ausreichende Bestätigung entscheidet, ob der Effekt eingetreten ist. Er muss ein expliziter, dauerhafter Zustand sein und keine Ausnahme, die beim Neustart eines Prozesses verschwindet. Protokollieren Sie mindestens Operations-ID, Daten oder eine sichere Zusammenfassung der Absicht, Versuchs-IDs, Zeitstempel, Idempotenzschlüssel, Ziel, Fehlerkategorie und jede Kennung, die vor dem Abbruch zurückgegeben wurde.

Der Abgleich folgt einer Hierarchie. Nutzen Sie zuerst eine Statusabfrage oder Ressourcen-ID, falls der Vertrag des Empfängers sie bereitstellt. Suchen Sie anschließend mit einem stabilen Kriterium nach dem Effekt im Zielsystem, etwa über die in Metadaten enthaltene Operations-ID. Bestätigen die Belege den Effekt, schließen Sie die Operation ohne Wiederholung ab. Belegen sie, dass er nicht angewendet wurde, können Sie entsprechend der Richtlinie einen neuen Versuch öffnen. Lassen sich beide Fälle nicht unterscheiden, nehmen Sie keine Abwesenheit an: Halten Sie den Fall offen und eskalieren Sie ihn, wenn das Risiko es rechtfertigt.

Eine menschliche Überprüfung ist kein Entwurfsfehler, sondern eine Sicherheitskontrolle für Operationen, deren Duplizierung mehr kostet als ihre Verzögerung. Die Eskalationsbedingungen müssen konkret sein: finanzielle Belastungen, irreversible Kommunikation, Änderungen an regulierten Datensätzen, Widersprüche zwischen Quellen, Ablauf der Deadline oder das Fehlen eines zuverlässigen Deduplizierungsnachweises.

Muster für strukturierte Ausgaben, Tools und Agenten

Bei strukturierten Ausgaben trennen Sie Validierung und Ausführung. Eine Antwort, die das Schema nicht erfüllt, darf nicht unmittelbar ein Tool speisen. Speichern Sie die empfangene Ausgabe, validieren Sie Typen, Pflichtfelder, Wertebereiche und die Berechtigung für die vorgeschlagene Aktion. Wenn Sie eine neue Generierung anfordern, behandeln Sie sie als neuen Versuch, einen Plan zu erzeugen, nicht als Nachweis dafür, dass zuvor kein Tool ausgeführt wurde.

Beim Tool Calling muss der Controller die Ausführungsautorität haben. Das Modell darf einen Aufruf vorschlagen, aber der Controller muss die Operations-ID vergeben, Berechtigungen prüfen, bei Bedarf semantisch gleichwertige Argumente deduplizieren und das Ergebnis protokollieren. Setzt der Agent nach einem Ausfall fort, muss er das Protokoll bereits ausgeführter Tools wiederherstellen; er darf den Verlauf nicht aus dem Text einer Unterhaltung ableiten.

Bei Agenten mit mehreren Schritten sollten Sie nicht den gesamten zusammengesetzten Ablauf als undurchsichtige Einheit wiederholen. Wiederholen Sie einzelne Schritte nur, wenn ihre Grenzen und Garantien bekannt sind. Eine Planung kann neu generiert werden; ein Lesevorgang kann mit Hinweis auf veränderliche Daten wiederholt werden; ein Schreibvorgang muss abgeglichen werden; und eine irreversible Aktion braucht eine explizite Schutzschwelle. Dieser Entwurf reduziert Duplikate und verbessert zugleich die Nachvollziehbarkeit bei Teilergebnissen.

Produktions-Checkliste und Grenzen dieses Leitfadens

Dokumentieren Sie vor der Aktivierung automatischer Wiederholungen für jede Operation Verantwortliche, Ziel, Effekte, Kosten einer Duplizierung, Idempotenzschlüssel, Bestätigungsnachweis, Deadline, maximale Versuchszahl und Eskalationsbedingung. Testen Sie Ausfälle an jeder Grenze: vor dem Senden, während der Übertragung, nachdem das Ziel die Anfrage akzeptiert hat, und bevor die lokale Antwort persistiert wird. Ein hilfreicher Test bestätigt, dass ein Prozessneustart keinen zweiten Effekt erzeugt.

Prüfen Sie die Architektur zudem im Kontext des Lernbereichs, der Sicherheitsdokumentation, der Preiskriterien und des Glossars Ihres Produkts. Wiederholungslimits beeinflussen Kosten und Latenz; die Aufbewahrung von Protokollen beeinflusst den Datenschutz; und Zugangsdaten, die für Abgleich oder Tool-Ausführung verwendet werden, müssen minimale Berechtigungen haben. Für konkrete Modelle wie GPT-6 Astra und Integrationen einer Organisation wie OpenAI muss die endgültige Richtlinie an den Vertrag und die tatsächlich für den verwendeten Endpunkt dokumentierten Fähigkeiten angepasst werden.

Die Abschlussregel ist einfach: Erklären Sie eine Operation nicht für erfolgreich, nur weil eine Anfrage gesendet wurde, und erklären Sie einen Effekt nicht für ausgeblieben, nur weil keine Antwort eingegangen ist. Erklären Sie eine Operation erst dann für geklärt, wenn die persistierten Belege ihren Status tragen. Fehlen diese Belege, kann die sichere Entscheidung darin bestehen, zu warten, abzugleichen oder menschliches Eingreifen anzufordern.

Weiter entdecken

Korrekturen und Transparenz

Wenn du falsche oder veraltete Angaben findest, sende uns die Seite und die zu prüfende Quelle.