Wiederholungsversuche bei KI-APIs: Fehler beheben, ohne Anfragen oder Kosten zu duplizieren

Ein Wiederholungsversuch ist keine harmlose Wiederholung

Einen API-Aufruf zu wiederholen bedeutet, eine Anfrage erneut zu senden, nachdem der vorherige Versuch keine für den Client verwertbare Antwort geliefert hat. Die Schwierigkeit besteht darin, dass „Ich habe keine Antwort erhalten“ nicht unbedingt bedeutet: „Der Server hat die Anfrage nicht verarbeitet.“ Die Verbindung kann vor dem Versand, während der Übertragung oder erst abbrechen, nachdem der Dienst die Anfrage bereits empfangen und ausgeführt hat. Im letzten Fall kann eine Wiederholung einen zweiten Vorgang oder eine zweite Abrechnung auslösen, obwohl der Client lediglich einen Netzwerkfehler gesehen hat.

Eine sinnvolle Strategie beginnt deshalb, bevor überhaupt eine Wartezeit zwischen Versuchen festgelegt wird. Zunächst muss klar sein, welcher Vorgang wiederholt wird, welches Ergebnis bekannt ist, welches Ergebnis ungewiss bleibt und welcher zusätzliche Aufwand zulässig ist. Eine neue Abfrage ohne externe Auswirkungen birgt ein anderes Risiko als ein Vorgang, der eine Aufgabe startet, Ressourcen verbraucht oder einen Zustand verändert. Ebenso sollte man die Wiederherstellung der Verfügbarkeit nicht mit der Garantie verwechseln, dass dieselbe Generierung nur ein einziges Mal ausgeführt wird: Diese Garantie hängt von den dokumentierten Fähigkeiten der API und der Gestaltung der Integration ab.

Diese Anleitung beschreibt Entscheidungen, die an den jeweiligen Anbieter angepasst werden müssen. Die hier genannten Dokumentationen von Kimi und ShareAI dienen als Referenz für die jeweiligen APIs. Die verfügbaren Ausschnitte bestätigen jedoch weder konkrete Fehlercodes noch Warte-Header oder Idempotenzmechanismen. Solche Einzelheiten dürfen nicht von einem Dienst auf einen anderen übertragen werden. Ebenso wenig sollte man annehmen, eine API biete eine Funktion an, nur weil sie bei anderen APIs verbreitet ist.

Den Fehler vor der Entscheidung klassifizieren

Fasse nicht jede fehlgeschlagene Antwort unter einer einzigen automatischen Regel zusammen. Unterscheide mindestens zwischen Fehlern aufgrund von Konfiguration oder Validierung, Antworten im Zusammenhang mit Nutzungslimits, abgelaufenen Wartezeiten und Verbindungsfehlern. Diese Klassifizierung ist ein Ausgangspunkt für die Untersuchung, aber keine universelle Tabelle von Fehlercodes: Jeder Anbieter definiert seine Antworten und deren Bedeutung selbst. Prüfe die aktuelle Dokumentation der API und halte fest, welche Signale in welchem Fall eine bestimmte Reaktion rechtfertigen.

Ein Validierungsfehler erfordert beispielsweise in der Regel eine Korrektur der Anfrage, nicht deren unveränderte Wiederholung. Bei einem Nutzungslimit kann es möglich sein, später fortzufahren; dafür muss jedoch die vom Dienst dokumentierte Vorgabe befolgt werden. Bei einem Timeout oder einer Verbindungsunterbrechung bleibt eine andere Frage offen: Hat der Dienst die Anfrage überhaupt erhalten? Lässt sich das nicht feststellen, sollte das Ergebnis als ungewiss eingestuft werden, statt einfach davon auszugehen, dass keine Verarbeitung stattgefunden hat. Diese Unterscheidung ist besonders wichtig, wenn der Vorgang Kosten oder wiederholte Auswirkungen verursachen kann.

Bei der Entscheidung für einen Wiederholungsversuch ist außerdem zu berücksichtigen, ob der Fehler vorübergehend erscheint, ob die Wiederholung derselben Anfrage sinnvoll ist und ob noch ein Zeit- und Versuchsbudget vorhanden ist. Die sekundäre Quelle zum Thema erneuter API-Aufruf oder Modellwechsel empfiehlt, Wiederholungen auf vorübergehende Fehler zu beschränken, sie nur für sicher wiederholbare Vorgänge vorzusehen und das verfügbare Budget einzuhalten. Das ist ein allgemeines Gestaltungskriterium, keine offizielle Fehlerdefinition für einen bestimmten Anbieter.

Eine ausdrückliche und begrenzte Richtlinie festlegen

Eine Wiederholungsrichtlinie sollte schriftlich festhalten, welche Fehler einen neuen Versuch auslösen dürfen, wie viele Versuche zulässig sind, wie lange der gesamte Ablauf dauern darf und was der Client beim Erreichen des Limits tut. Unterscheide den ersten Versand von den Wiederholungsversuchen. Wenn eine maximale Gesamtzahl von Versuchen festgelegt wird, muss angegeben werden, ob die ursprüngliche Anfrage mitgezählt wird. Diese Genauigkeit verhindert unterschiedliche Auslegungen in Code, Konfiguration und Metriken.

Das Gesamtzeitlimit – manchmal als Zeitbudget bezeichnet – sollte sowohl Wartezeiten als auch spätere Aufrufe umfassen, nicht nur die Verbindungsdauer eines einzelnen Versuchs. Läuft das Budget ab, dürfen keine weiteren Wiederholungen geplant werden, auch wenn das Versuchslimit noch nicht erreicht ist. Umgekehrt muss die Sequenz beim Erreichen der Höchstzahl enden, selbst wenn noch Zeit übrig ist. So werden unbegrenzte Schleifen und Anfragen vermieden, die Ressourcen lange weiter beanspruchen, nachdem der Aufrufer das Ergebnis nicht mehr verwenden kann.

Es gibt keine für alle APIs geeignete Anzahl von Versuchen oder allgemeingültige Dauer. Begründe diese Parameter anhand der von der Anwendung tolerierten Latenz, der Hinweise des Anbieters, der potenziellen Kosten des Vorgangs und des unter Fehlerbedingungen gemessenen Verhaltens. Die Kimi-Hilfedokumentation erwähnt exponentielles Warten und die Begrenzung der Anzahl von Anfragen. Der verfügbare Ausschnitt gibt weder universelle Werte vor noch bestätigt er, dass diese Vorgehensweise für sämtliche Fehler gilt.

Wenn die Dokumentation einer API ein Warte-Signal vorgibt, prüfe dessen Bedeutung und Geltungsbereich und befolge die Anweisung des Anbieters. Erfinde weder den Namen eines Headers noch lege ein Signal eines anderen Dienstes als gleichbedeutend aus. Wurde kein dokumentiertes Signal überprüft, sollte der Client nicht so tun, als könne er daraus den richtigen Zeitpunkt für die Fortsetzung ableiten.

Progressive Wartezeiten und zufällige Streuung

Bei einer progressiven Wartezeit werden die Abstände zwischen aufeinanderfolgenden Versuchen länger. Das kann den Druck verringern, der durch unmittelbar wiederholte Aufrufe entsteht, wenn ein Dienst überlastet ist oder eine Störung hat. Die Dokumentation zur Fehlerbehebung von Kimi erwähnt exponentielles Warten zusammen mit der Begrenzung der Anzahl von Anfragen. Diese Referenz belegt, dass die Konzepte in der Kimi-Dokumentation behandelt werden. Sie legt weder eine für andere APIs gültige Konfiguration fest noch beweist sie, dass eine bestimmte Wartezeit in allen Fällen geeignet ist.

Zufällige Streuung, auch Jitter genannt, variiert die Pausen, damit viele Clients, bei denen gleichzeitig ein Fehler auftrat, ihre Anfragen nicht synchron erneut senden. Das ist ein mögliches Gestaltungsmittel, aber keine allgemeingültige Pflicht. Prüfe, ob es zu den veröffentlichten Vorgaben des Anbieters und zum maximalen Zeitrahmen des Vorgangs passt. Gibt es eine dokumentierte Warteanweisung, sollte sie nicht durch eine zufällige Pause ersetzt werden, die ihr möglicherweise widerspricht.

Dokumentiere die gewählten Parameter und die Begründung für jeden einzelnen: wie die Wartezeiten ansteigen, wo ihre Obergrenze liegt, welche Streuung angewendet wird und wie der Ablauf beim Ablauf des Zeitbudgets beendet wird. Miss die Auswirkungen anhand betrieblicher Daten: Anzahl der Versuche pro Anfrage, Erfolg nach einer Wiederholung, Gesamtdauer, endgültige Fehler und – sofern messbar – damit verbundener Verbrauch. Verwandle eine allgemeine Empfehlung nicht ohne Tests mit dem tatsächlichen Anbieter und der realen Last in einen universellen Zahlenwert.

Duplikate verhindern: Idempotenz und ungewisse Ergebnisse

Idempotenz ist eine Eigenschaft, durch die eine Operation wiederholt werden kann, ohne dass die Wiederholungen zusätzliche Auswirkungen haben – innerhalb der vom System festgelegten Bedingungen. Bei einer API genügt es nicht, den Begriff auf einer Dokumentationsseite zu finden. Kläre, ob der Anbieter einen Idempotenzschlüssel oder einen gleichwertigen Mechanismus anbietet, welche Endpunkte oder Vorgänge abgedeckt sind, wie der Mechanismus übermittelt wird, wie lange er erkannt wird und was geschieht, wenn derselbe Schlüssel mit anderen Parametern wiederverwendet wird. Nur die aktuelle Dokumentation des Anbieters kann solche Garantien bestätigen.

Die verfügbaren Quellen bestätigen keine Idempotenzunterstützung für Kimi oder ShareAI. Auf der ShareAI-Seite wird ausdrücklich darauf hingewiesen, dass bei Schreibvorgängen besondere Vorsicht geboten ist. Der Ausschnitt bestätigt jedoch weder einen bestimmten Schlüssel noch eine konkrete Garantie. Daher sollte nicht behauptet werden, einer dieser Anbieter dedupliziere Anfragen standardmäßig. Wenn die API keinen anwendbaren Mechanismus dokumentiert, muss eine Verbindungstrennung nach dem Versand als potenziell ungewisses Ergebnis behandelt werden. Prüfe, ob der Anbieter einen Mechanismus zur nachträglichen Abstimmung vorsieht, und nutze ihn gegebenenfalls.

Unterscheide zwischen einer erneuten Abfrage eines bereits identifizierten Vorgangs und dem Start eines neuen Vorgangs. Ist in der API ein abfragbarer Bezeichner dokumentiert, verwende ihn nur innerhalb des beschriebenen Geltungsbereichs und Lebenszyklus. Gibt es keine dokumentierte Möglichkeit, das Ergebnis zu überprüfen, muss die Integration entscheiden, ob sie anhält, die Unsicherheit meldet oder eine Wiederholung mit ausdrücklich benanntem Risiko zulässt. Eine Ausführung genau einmal darf nicht versprochen werden, solange keine überprüfte Garantie den konkreten Fall abdeckt.

Durchgearbeitetes Beispiel: Die Antwort geht nach dem Versand verloren

Stell dir vor, eine Anwendung sendet eine Generierungsanfrage. Der Client wartet auf die Antwort, doch die Verbindung bricht ab. Er weiß nicht, ob der Server die Anfrage erhalten, mit der Verarbeitung begonnen oder sie bereits abgeschlossen hat. Statt automatisch erneut zu senden, markiert er den Versuch als ungewiss und prüft die Dokumentation dieser API: Gibt es einen anwendbaren Idempotenzschlüssel? Gibt es eine dokumentierte Möglichkeit, den Status abzufragen? Welche Vorgehensweise sieht der Anbieter für eine solche Unterbrechung vor? Die Antworten bestimmen den nächsten Schritt.

Gibt es einen dokumentierten Mechanismus, der diesen Vorgang abdeckt, kann die Integration ihn innerhalb seines genau beschriebenen Geltungsbereichs zum Wiederholen oder Abfragen nutzen. Gibt es keinen solchen Mechanismus, lässt sich aus dem Transportfehler nicht ableiten, dass der Dienst die Anfrage nicht verarbeitet hat. Das Team muss die zuvor genehmigte Risikopolitik anwenden: Es kann beispielsweise anhalten und einen Status anzeigen, der einer Überprüfung bedarf, oder eine Wiederholung zulassen und dabei darauf hinweisen, dass dadurch weiterer Verbrauch entstehen könnte. Welche Möglichkeit angemessen ist, hängt von den Folgen eines Duplikats und den verfügbaren Mechanismen ab; eine universelle Antwort gibt es nicht.

Liefert der Anbieter eine endgültige Antwort, wird der Ablauf gemäß der dokumentierten Bedeutung dieser Antwort beendet. Bei Erfolg werden keine weiteren Versuche geplant. Wird ein vorübergehender Fehler bestätigt und ist eine Wiederholung sicher, werden Limit, Budget und Wartezeit erneut geprüft. Läuft das Budget ab oder wird die Höchstzahl erreicht, endet die Sequenz; das System protokolliert das endgültige oder ungewisse Ergebnis. Der Zähler darf nicht einfach zurückgesetzt werden, nur weil ein anderer Prozess die Anfrage weiterbearbeitet.

Realistische Fehler vor der Bereitstellung testen

Tests müssen sowohl die Entscheidung für einen neuen Versuch als auch die Entscheidung zum Anhalten überprüfen. Simuliere einen Fehler, den die Konfiguration als vorübergehend einstuft, und prüfe, ob der Client das Limit einhält. Simuliere anhaltende Fehler und bestätige, dass keine unbegrenzten Wiederholungen stattfinden. Lass das Zeitbudget ablaufen, obwohl noch Versuche übrig wären; prüfe anschließend auch, ob das Erreichen der Höchstzahl den Ablauf beendet, selbst wenn noch Zeit verfügbar ist.

Nimm eine verspätete Antwort und eine Verbindungsunterbrechung direkt nach dem Versand in die Tests auf. Das sind unterschiedliche Fälle: Eine verspätete Antwort kann eintreffen, nachdem der Client seine Wartezeit bereits als abgelaufen betrachtet. Bei einer Unterbrechung nach dem Versand bleibt hingegen der Verarbeitungsstatus ungewiss. Prüfe, ob die Anwendung einen Vorgang dupliziert, weil sie fälschlich annimmt, beide Situationen bedeuteten, dass der Server „nichts getan“ habe. Bietet der Anbieter eine Idempotenzfunktion, muss ihr Geltungsbereich in einer geeigneten Umgebung anhand der aktuellen Dokumentation getestet werden. Eine Garantie, die der Dienst nicht versprochen hat, darf nicht einfach simuliert werden.

Ergänze Validierungsfehler und Nutzungslimits, um sicherzustellen, dass eine allgemeine Regel nicht auf jede Antwort angewendet wird. Gibt es vom Anbieter veröffentlichte Warte-Signale, teste ihre dokumentierte Auslegung. Prüfe abschließend, ob die Protokolle den zeitlichen Ablauf der Versuche rekonstruierbar machen, ohne Prompts, Antworten oder sensible Daten unnötig zu speichern. Korrelationskennungen, Ergebnistyp, Zeitangaben und Versuchsnummer sind für die Diagnose oft nützlicher, als den gesamten Anfrageinhalt zu kopieren.

Kriterien für die Einführung der Richtlinie in der Produktion

Halte vor der Bereitstellung fest, welche Dokumentation du konsultiert hast, wann sie überprüft wurde und für welche Version oder welchen Endpunkt sie gilt. Trenne die Vorgaben des Anbieters von den Entscheidungen der eigenen Anwendung: Eine dokumentierte Empfehlung ersetzt nicht die Bewertung des Duplikatrisikos, und eine lokale Richtlinie darf nicht als Garantie des Dienstes dargestellt werden.

Überprüfe die Ergebnisse nach der Bereitstellung. Ein Anstieg der Versuche pro Anfrage, der ausgeschöpften Abläufe oder der ungewissen Ergebnisse kann auf eine Verschlechterung, eine zu aggressive Konfiguration oder eine Änderung im Verhalten des Dienstes hindeuten. Behandle Fallback – etwa eine genehmigte alternative Route – als eine andere Entscheidung als den Wiederholungsversuch. Die sekundäre Quelle zu LLM-APIs empfiehlt, nur auf eine zuvor genehmigte Alternative auszuweichen. Prüfe Kompatibilität, Qualität, Datenschutz und Kosten, bevor du einen Fallback aktivierst. Er sollte nicht verschleiern, dass die ursprüngliche Anfrage möglicherweise verarbeitet wurde.

Miss zum Schluss die technische Wiederherstellung getrennt von der Qualität der Antwort. Dass ein Aufruf nach mehreren Versuchen erfolgreich endet, beweist nicht, dass der generierte Inhalt korrekt oder angemessen ist. Eine robuste Richtlinie begrenzt Schäden und schafft Klarheit über Ergebnisse. Sie ersetzt weder die Bewertung der Modellausgabe noch die Sicherheitsentscheidungen der Anwendung.

Weiter entdecken

Korrekturen und Transparenz

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