GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
Alle Anleitungen

· reAPI Team

API-500-Fehler: Wann du eine Videoanfrage wiederholen solltest

Behandle API-500-Fehler, ohne kostenpflichtige Videojobs zu duplizieren. Prüfe, ob die Übermittlung angenommen wurde, stelle Task-IDs wieder her, begrenze Wiederholungen und setze Workflows sicher fort.

API-500-Fehler: Wann du eine Videoanfrage wiederholen solltest

Ein Klick, eine Fehlermeldung, dann ein weiterer Klick. In einer Videoanwendung kann das genügen, um zwei kostenpflichtige Generierungen zu erstellen, obwohl die Oberfläche weiterhin einen Fehler anzeigt.

Stell dir eine hypothetische Anfrage vor: Der Server nimmt die erste Übermittlung an, startet einen Task und verliert die Antwort auf dem Weg zurück zum Client. Der Client erhält einen Fehler und sendet die Anfrage erneut. Wenn der Endpunkt für jede angenommene Übermittlung einen neuen Task erstellt, können beide Jobs weiterlaufen. Der zweite Klick hat die erste Antwort nicht repariert, sondern ein weiteres Video angefordert.

Das ist die praktische Schwierigkeit bei API-500-Fehlern. Die AWS-Anleitung zu Wiederholungen warnt, dass eine fehlgeschlagene Antwort oder ein Timeout nicht belegt, dass der Vorgang keine Nebenwirkungen hatte.[1] Finde vor einer erneuten Generierung heraus, was die fehlgeschlagene Anfrage tat und welche Belege für ihre Annahme noch vorhanden sind.

Finde die fehlgeschlagene Anfrage

Eine Meldung wie „Request failed with status code 500“ benennt ein HTTP-Ergebnis, nicht den Zustand des Videos. MDN definiert 500 als einen unerwarteten Serverzustand, der die Erfüllung der Anfrage verhindert hat.[2] Die Meldung sagt dir nicht, welche Komponente ausgefallen ist, beweist nicht, dass jede Eingabe gültig war, und verspricht nicht, dass Warten das Problem behebt.

Prüfe Methode und URL im Client-Log. Ein Fehler beim Generierungs-POST hat andere Folgen als ein Fehler beim Abrufen eines vorhandenen Tasks. Ein Dateidownload kann scheitern, nachdem beide Vorgänge erfolgreich waren. Eine Oberfläche, die alle drei Fälle zu „Generierung fehlgeschlagen“ zusammenfasst, verliert die für die Wiederherstellung nötige Unterscheidung.

Halte UTC-Zeit, Modell, Status, Antworttext sowie eine verfügbare Anfrage- oder Task-ID fest. Entferne Zugangsdaten, bevor du Logs teilst. Wenn die Antwort HTML statt des dokumentierten API-Fehlerformats ist, halte auch das fest; leite aus einer allgemeinen Fehlerseite keinen vermuteten Modellfehler ab.

Bei dem hypothetischen ersten Klick ist die Frage, ob du eine Task-ID hast. Suche nach der auf deinem Server gespeicherten Antwort auf die Übermittlung, der relevanten Workflow-Ausgabe und einem dokumentierten Callback-Eintrag. Prüfe das Konto oder Projekt, von dem die Anfrage tatsächlich gesendet wurde. Ein anderes Dashboard-Konto kann nicht klären, ob diese Übermittlung einen Job erstellt hat.

Mit einer Task-ID setzt du bei diesem Task fort

Wenn du die Kennung wiederhergestellt hast, nutze den dokumentierten Lesevorgang des Anbieters. Bei reAPI ruft GET /api/v1/tasks/{id} den Task ab, ohne Credits zu verbrauchen.[3] Nutze ihn, um die Beobachtung fortzusetzen; sendest du denselben Generierungs-Body erneut, entsteht eine separate Übermittlung.

Lies den Task-Status in der Antwort. reAPI gibt HTTP 200 zurück, wenn ein Task gefunden wird, auch wenn sein Status failed ist.[4] HTTP 200 bedeutet also nicht, dass das Video erfolgreich war. Ebenso beweist ein 500 beim Abruf nicht, dass das Video fehlgeschlagen ist. Es bedeutet, dass du mit diesem Abruf keine brauchbare Antwort erhalten hast.

Verarbeite einen abgeschlossenen Task mit den dokumentierten Ausgabefeldern. Speichere die benötigte Datei, statt die Anwendung auf eine zweite Generierung warten zu lassen. Ein Task in Bearbeitung wird weiter beobachtet. Lies bei einem fehlgeschlagenen Task den Fehler und die Abrechnungsinformationen, bevor du entscheidest, ob ein neuer Versuch sinnvoll ist.

Der fehlgeschlagene Task und seine Abrechnung hängen zusammen, sind aber verschiedene Dinge. reAPI dokumentiert Rückerstattungen für fehlgeschlagene Tasks und modellspezifische Fälle, in denen eine Sicherheitsprüfung nach der Generierung eine Ausgabe blockieren kann, obwohl eine abrechenbare Generierung stattgefunden hat.[3] Bewahre den tatsächlichen Nutzungsdatensatz des Tasks auf. Ein allgemeines Banner „Serverfehler“ belegt nicht, dass sämtliche Gebühren entfallen müssen; die Abrechnung fehlgeschlagener Generierungen muss anhand des endgültigen Task-Status und der geltenden Richtlinie beurteilt werden.

Ohne ID bleibt offen, ob die Anfrage angenommen wurde

Der schwierigere Fall ist der erste Klick ohne brauchbare Antwort auf die Übermittlung. Gib diesem Vorgang in deiner Anwendung ausdrücklich einen ungeklärten Status. Ein interner Wert wie acceptance_unknown kann ihn etwa von nie gesendeter Arbeit und von Arbeit unterscheiden, deren Fehlschlagen der Anbieter bestätigt hat. Das ist ein vorgeschlagener Anwendungsstatus, kein Feld, das jede API zurückgibt.

Behalte eine stabile lokale Vorgangs-ID und lege eine zuständige Stelle für die Wiederherstellung fest. Sie kann die Belege abgleichen, die die Integration tatsächlich bereitstellt: gespeicherte Antworten, Callbacks, autorisierte Task-Historie oder Ergebnisse einer Support-Anfrage. Wird später ein Task identifiziert, ordne ihn dem ursprünglichen Vorgang zu und setze dort fort.

Eine leere lokale Task-ID-Spalte beweist nur, dass deine Anwendung keine ID gespeichert hat. Die Antwort könnte nach der Annahme verloren gegangen sein. Ebenso wird deine lokale Vorgangs-ID nicht automatisch an den Anbieter übermittelt und veranlasst dessen Erstellungsendpunkt nicht, Anfragen zu deduplizieren. Sie hilft, deine Belege zu ordnen; sie beweist keine genau einmalige Ausführung.

Gehe auch mit einem Idempotency-Key-Header vorsichtig um. HTTP POST ist nicht von sich aus idempotent; ob eine Wiederholung sicher ist, hängt vom tatsächlichen Vertrag des Endpunkts ab.[5] reAPI erklärt ausdrücklich, dass dieser Header aufgezeichnet, aber nicht zur Deduplizierung von Generierungen verwendet wird. Ein angenommener POST kann bei Wiederholung mit demselben Schlüssel einen weiteren Task und eine weitere Gebühr erzeugen.[6]

Bleiben die Belege uneindeutig, kann ein bewusst gestarteter Ersatz trotzdem eine Geschäftsentscheidung sein. Halte ihn als weiteren Versuch fest, der dem ungeklärten ursprünglichen Vorgang zugeordnet ist, und berücksichtige, dass beide abgeschlossen werden können. Ändere den ersten Versuch nicht stillschweigend in „nicht erstellt“, nur um die Wiederholungsschlange zu vereinfachen. Damit würdest du genau den Datensatz löschen, den du brauchst, wenn später ein Ergebnis oder eine Gebühr eintrifft.

Prüfe, was n8n erneut ausführt

Dieselbe Unklarheit wird in einem Workflow-Editor leicht übersehen. Ein Knoten mit der Bezeichnung „Generate Video“ kann Arbeit übermitteln und anschließend auf sie warten. Ein roter Knoten kann bedeuten, dass die Wartezeit abgelaufen ist, während die entfernte Vorhersage weiterläuft.

Die offizielle n8n-Integration-Dokumentation von WaveSpeed beschreibt genau dieses Verhalten: Der Generierungsknoten übermittelt eine Vorhersage und wartet auf das Ergebnis. Ein positiver Timeout kann den Knoten fehlschlagen lassen, während die Vorhersage weiterläuft. Die Dokumentation warnt, dass n8ns Retry On Fail den gesamten Knoten erneut ausführt und dadurch eine neue, separat abgerechnete Vorhersage entsteht; vorübergehende Fehler beim Polling werden bereits intern wiederholt.[7] Diese Warnung gilt für diese Integration, nicht automatisch für jeden Community-Knoten.

Bei einem Workflow mit HTTP-Request-Knoten prüfe die Aktion des Knotens, für den Wiederholungen konfiguriert sind. n8n dokumentiert Retry on Fail als Einstellung auf Knotenebene.[8] Sendet dieser Knoten den Generierungs-POST, sendet ein weiterer Versuch diesen POST erneut. Liest er lediglich einen bekannten Task aus, wird der Lesevorgang wiederholt. Der sichtbare Fehlertext des Workflows ersetzt die Prüfung des Knotens nicht.

Ein sinnvolles Design speichert die angenommene Task-ID dauerhaft zwischen Übermittlung und Polling. So kann die Wiederherstellung beim Lesen fortsetzen, ohne den Erstellungsprozess erneut zu durchlaufen. Damit ist der oben beschriebene Fall einer verlorenen Übermittlungsantwort nicht gelöst; halte diesen ungeklärten Pfad separat. Auch das manuelle erneute Ausführen eines vollständigen Durchlaufs muss geprüft werden, denn bereits erfolgreiche Erstellungsschritte können erneut laufen.

Zurück zum hypothetischen Doppelklick: Wird der zweite Klick durch eine automatische Wiederholung des Knotens ersetzt, ändert das nichts am Abrechnungsproblem. Die Anwendung muss weiterhin wissen, ob sie den ursprünglichen Job abfragt oder einen neuen anfordert.

Wiederhole den Lesevorgang mit einem Stopppunkt

Ein vorübergehender Fehler beim Lesen eines bekannten Tasks eignet sich eher für eine Wiederholung. Verwende dieselbe Task-Kennung, halte dich an die dokumentierten Polling- und Ratenbegrenzungsregeln des Endpunkts und stoppe die unmittelbare Wiederholungsschleife, wenn die erlaubte Anzahl von Versuchen oder das Zeitbudget ausgeschöpft ist.

AWS beschreibt begrenztes exponentielles Backoff, Jitter und Versuchslimits, damit eine angeschlagene Abhängigkeit nicht überlastet wird.[1] Jitter verteilt die nächsten Versuche der Clients zeitlich, statt sie alle für denselben Moment anzusetzen. Diese Techniken steuern die Wiederholungslast; sie machen aus einem Erstellungs-POST keinen deduplizierten Vorgang.

Bestimme eine Ebene, die für diese Wiederherstellung zuständig ist. Wenn ein SDK, ein Workflow-Knoten und ein äußerer Worker jeweils unabhängig wiederholen, kann der entstehende Datenverkehr die Erwartungen der äußeren Einstellung übersteigen. Prüfe die bereits in der Integration eingebauten Wiederholungen, bevor du eine weitere Schleife hinzufügst.

Wenn das Lesebudget endet, behalte die Task-ID für einen späteren Abgleich. Eine Client-Deadline sagt, wie lange dieser Client gewartet hat. Solange kein dokumentierter Abbruchvorgang erfolgreich war, beweist sie nicht, dass die entfernte Generierung gestoppt wurde. Zeige einen ungeklärten Abrufstatus an, statt eine uneingeschränkte Schaltfläche „Erneut versuchen“ anzubieten, die neue Arbeit übermittelt.

Prüfe den konkreten Fehler, bevor du einen Ersatz auswählst

Wenn du einen strukturierten Fehler hast, lies dessen Code und den dokumentierten Geltungsbereich. reAPI nennt zum Beispiel 60001 und 60002 als Fehler beim Speichern eines Tasks oder Starten eines Workflows und erklärt, dass Credits erstattet werden.[4] Diese dokumentierten Fälle stützen eine andere Wiederherstellungsentscheidung als eine unbekannte HTML-500-Antwort oder eine nach der Übermittlung verlorene Verbindung. Übertrage die Rückerstattung nicht auf jeden Serverfehler.

Wenn die konkrete Antwort eine ungültige Eingabe oder nicht verwendbare Medien benennt, behebe das angegebene Problem anhand der Dokumentation des Endpunkts, bevor du einen weiteren Versuch sendest. Bewahre die Belege des ursprünglichen Versuchs auf und behandle die korrigierte Übermittlung als neue Arbeit; eine Eingabe zu ändern klärt nicht, ob die frühere Anfrage angenommen wurde.

Auch „Der Server kann diese Anfrage derzeit nicht verarbeiten“ ist ohne HTTP-Status und Antwortdetails unvollständig. Den Prompt wiederholt zu ändern, den Browser zu aktualisieren oder das Timeout zu erhöhen, verrät nicht, an welcher Stelle der serverseitige Fehler auftrat. Bei einem vom Anbieter verwalteten Endpunkt übermittle über dessen Supportprozess Methode, URL, UTC-Zeit und verfügbare Kennungen; reAPIs Fehlerleitfaden nennt diese Belege.[4]

Ein anderer Anbieter kann ein sinnvoller Ersatz sein, wenn seine unterstützten Eingaben, Ausgaben und Betriebsbedingungen zur Aufgabe passen. Ein anderer Hostname allein beweist jedoch keinen unabhängigen Fehlerpfad. Ein erfolgreicher Ersatz klärt auch nicht, was mit der ursprünglichen Übermittlung geschah. Halte beide Versuche sichtbar, einschließlich eines ursprünglichen Tasks, der später abgeschlossen wird.

Bevor du einen Rückstand fortsetzt, erfasse die bereits gesendete Arbeit. Bekannte Tasks müssen weiter beobachtet oder mit einem Ergebnis versehen werden; für unbekannte Übermittlungen braucht es eine zuständige Person und eine ausdrückliche Entscheidung über einen Ersatz. Der erste erfolgreiche Wiederholungsversuch ist hilfreich. Verständlich wird die Wiederherstellung aber erst, wenn du erklären kannst, welche entfernten Jobs es für jede Nutzeranfrage geben könnte.

Referenzen

  1. AWS Builders Library: Timeouts, retries, and backoff with jitter. Technische Leitlinien, erstmals 2019 veröffentlicht; Nebenwirkungen, begrenzte Wiederholungen und Verstärkung durch Wiederholungen.
  2. MDN: HTTP 500 Internal Server Error. Definition und serverseitige Untersuchung.
  3. reAPI Tasks. Polling, Status, Ausgabe und Abrechnungssemantik.
  4. reAPI Errors. Spezifische Fehlercodes und Belege für den Support. Die Wiederholungsentscheidungen hier berücksichtigen auch den Übermittlungsvertrag aus Referenz 6.
  5. MDN: Idempotent. Semantik von HTTP-Methoden und die Grenzen der Annahme, dass eine Wiederholung sicher ist.
  6. reAPI API-Übersicht. Vertrag zur Generierungsübermittlung und zu Idempotency-Key.
  7. Offizielle WaveSpeed-Dokumentation zur n8n-Integration. Knoten-Timeout, Wiederholung des gesamten Knotens und separat abgerechnete Vorhersagen; abgerufen am 15. November 2026.
  8. Offizielle n8n-Dokumentation zu häufigen Problemen mit HTTP Request. Retry on Fail und Einstellungen für Knotenwiederholungen; abgerufen am 15. November 2026.
Alle Anleitungen