Text-to-Video-API-Fehlercodes erklärt

Die meisten Fehler bei Text-to-Video-APIs lassen sich auf 5 Kategorien zurückführen: fehlerhafte Anfragen, Auth-Probleme, Ratenlimits, Sicherheitssperren oder Serverprobleme. Wenn ich den HTTP-Status, den vollständigen Fehler-Body, die Request- oder Task-ID und den Zeitpunkt des Fehlers prüfe, finde ich die Ursache meist schnell.

Hier die Kurzfassung:

• Fehler der 400er-Reihe bedeuten meist, dass ich die Anfrage korrigieren muss.
• 401/403 deuten meist auf API-Schlüssel, Zugriff, Abrechnung oder IP-Regeln hin.
• 429 bedeutet, dass ich ein Request-, Job- oder Ausgabenlimit erreicht habe.
• 200 OK beim Absenden bedeutet nicht, dass das Video fertig ist. Ich muss den Job trotzdem abfragen und auf failed prüfen.
• Fehler der 500er-Reihe erfordern oft einen Retry, aber nur, nachdem ich geprüft habe, ob der Job noch läuft.
• Sicherheitssperren können vor, während oder nach der Generierung auftreten, und manche APIs geben möglicherweise weniger Clips zurück, anstatt den ganzen Job scheitern zu lassen.

Ein paar Zahlen stechen heraus. Video-Jobs, wie die mit Sora 2, können eine GPU 30–90 Sekunden lang belegen, Client-Timeouts müssen unter Umständen 10+ Minuten betragen, und ein gängiger Retry-Plan lautet: bei 5 Sekunden beginnen, bei 60 Sekunden deckeln, nach 3 Versuchen aufhören.

Wenn ich weniger fehlgeschlagene Jobs und weniger doppelte Kosten will, halte ich den Workflow einfach:

• Fehler-Body und Task-ID protokollieren
• Fehler auf API-Ebene von Fehlern auf Job-Ebene trennen
• Nur bei 429- und 5xx-Fällen einen Retry durchführen
• Task-Status prüfen, bevor ich denselben Job erneut absende
• Genaue Modellversionen fixieren, statt Aliase wie latest zu verwenden

API-Fehlermeldungen für eine GUTE Entwicklererfahrung

Kurzvergleich

Einfach gesagt: Erfolg beim Absenden ist nicht Erfolg beim Rendern. Ich würde Polling-Ergebnisse als maßgebliche Quelle betrachten und den Fehler-Payload — nicht nur den Statuscode — nutzen, um über das weitere Vorgehen zu entscheiden.

Client-seitige Anfragefehler: 400er-Codes, die du beheben kannst

Nachdem du die Fehlerdetails protokolliert hast, gilt es als Nächstes herauszufinden, was auf der Anfrageseite schiefgelaufen ist. Beginne mit dem Fehler-Body und ordne dann den HTTP-Code der Lösung zu.

400, 404, 413 und 415: Was jeder Code für Videoanfragen bedeutet

Jeder Code deutet auf eine andere Art von Anfragefehler hin. Ein 400 bedeutet meist fehlerhaftes JSON, fehlende Pflichtfelder oder ungültige Parametertypen. Zum Beispiel schlägt die Validierung fehl, wenn duration als String ("6") statt als Ganzzahl (6) übergeben wird ^[4]. Ein 404 bedeutet, dass die Modell-ID oder der Endpunkt-Pfad falsch ist, oft wegen eines kleinen Tippfehlers wie wan2.7 statt [wan-2.7](https://apimart.ai/ja/model/wan-2-7) oder [wan-2.6](https://apimart.ai/model/wan-2-6) ^[7]. Ein 413 tritt auf, wenn ein Referenzbild oder -video größer ist als das Upload-Größenlimit ^[4][7]. Ein 415 bedeutet, dass der Content-Type-Header falsch ist oder das Dateiformat vom Modell nicht unterstützt wird ^[5].

Modell- und Parameter-Diskrepanzen, die Validierungsfehler verursachen

Selbst wenn dein JSON sauber ist, können Anfragen die Validierung trotzdem nicht bestehen, weil nicht alle Modelle denselben Regeln folgen. Auflösung, Dauer, Seitenverhältnis und Asset-Limits können von Modell zu Modell variieren.

Nimm MiniMax-Hailuo-2.3. Es unterstützt 10 Sekunden bei 768p, aber wenn du 1080p anforderst, sinkt die maximale Dauer auf 6 Sekunden ^[6]. Asset-Regeln können ebenso streng sein. Kling 3.0 verlangt, dass Eingabebilder in beiden Dimensionen mindestens 300 px groß sind, mit einem Seitenverhältnis zwischen 1:2.5 und 2.5:1. Wan 2.7 verlangt, dass Referenzvideos 2–10 Sekunden lang und nicht größer als 100 MB sind ^[4][7].

Ein 422 bedeutet meist, dass deine Parameter miteinander in Konflikt stehen. Zum Beispiel gibt SkyReels V4 einen 422 zurück, wenn du Image-to-Video- und Omni-Felder in derselben Anfrage kombinierst ^[8].

Eine kleine Gewohnheit kann viel Zeit sparen: Verwende fixierte Versions-Strings statt generischer Aliase. Parameter-Regeln können sich zwischen Modellversionen ändern ^[3]. Wenn die Validierung weiterhin fehlschlägt, prüfe die genauen Limits des Modells, bevor du es erneut versuchst.

Wenn die Anfrage die Validierung besteht, aber trotzdem fehlschlägt, geht es als Nächstes um Authentifizierung, Ratenlimits und Sicherheitsprüfungen.

Authentifizierung, Berechtigungen und Ratenlimits

Sobald die Validierung bestanden ist, lassen sich die meisten verbleibenden Fehler auf drei Dinge zurückführen: Auth, Berechtigungen oder Ratenlimits.

401 und 403: API-Schlüssel- und Zugriffsfehler

Ein 401 Unauthorized-Fehler bedeutet, dass die Anfrage keine gültigen Authentifizierungsdaten enthielt. Die üblichen Ursachen sind ein fehlender API-Schlüssel, ein ungültiger Schlüssel, ein deaktivierter oder gelöschter Schlüssel oder ein fehlerhafter Authorization-Header ^[9][1][2].

Viele APIs erwarten:

Authorization: Bearer YOUR_API_KEY

Manche Plattformen verwenden stattdessen x-api-key. Wenn also der Header-Name oder das Format nicht stimmt, kann allein das einen 401 auslösen ^[1][10].

Beginne mit den Grundlagen. Prüfe die Umgebungsvariable, stelle sicher, dass der Schlüssel noch aktiv ist, und bestätige, dass dein CI/CD-Setup Secrets in jeder Umgebung korrekt einspeist ^[3]. Es hilft auch, den Response-Body zu lesen, anstatt beim HTTP-Statuscode aufzuhören. Fehler wie invalid_api_key, token_expired oder account_banned sagen dir meist viel schneller, was kaputt ist ^[9][3].

Ein 403 Forbidden bedeutet, dass der Server dich erkannt, die Anfrage aber trotzdem blockiert hat. Das deutet meist auf ein Zugriffsproblem hin. Dein Schlüssel hat möglicherweise nicht den richtigen Modell-Scope, dein Kontoplan schließt diesen Endpunkt möglicherweise nicht ein, deine Credits sind aufgebraucht, oder deine Request-IP steht möglicherweise nicht auf der Allowlist ^[3][9].

Der Response-Body ist auch hier wichtig. Wenn du insufficient_credits siehst, schau in die Abrechnung. Wenn du permission_error siehst, prüfe Scopes, Modellzugriff oder Planlimits. Und wenn der Zugriff in Ordnung aussieht, aber der Traffic zu hoch ist, folgt meist als Nächstes ein 429.

429: Fehler bei Ratenlimit und Kontingentüberschreitung

Wenn die Auth erfolgreich ist, ist das Anfragevolumen oft der nächste Engpass. Ein 429 Too Many Requests-Fehler bedeutet, dass du auf eine Drosselung, ein Nebenläufigkeitslimit oder ein Ausgabenlimit gestoßen bist ^[3][9][10]. Im Klartext: Du hast in kurzer Zeit zu viele Anfragen gesendet, zu viele Jobs gleichzeitig ausgeführt oder ein Abrechnungslimit überschritten ^[3][9].

Auch hier liefert der Response-Body den besten Hinweis. rate_limit_exceeded bedeutet meist, dass du exponentielles Backoff verwenden solltest. spend_limit_exceeded bedeutet, dass es Zeit ist, die Abrechnungseinstellungen zu prüfen ^[3][9].

Stelle Batch-Jobs lokal in eine Warteschlange, wenn möglich, und behalte diese Header im Auge ^[2]:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Wenn du APIMart nutzt, kann ein Schlüssel über alle Modelle hinweg die Auth-Streuung reduzieren ^[3]. Selbst dann bleibt der Debugging-Ablauf ungefähr gleich: Lies den Response-Body, überprüfe deine Umgebungsvariablen und stelle sicher, dass das Konto auf das Modell zugreifen kann, das du aufrufst.

Sicherheitssperren, Timeouts und serverseitige Fehler

Nachdem Anfragevalidierung und Auth bestanden sind, fallen die verbleibenden Fehler meist in zwei Kategorien: Moderationssperren und serverseitige Probleme. Sobald Auth, Kontingent und Validierung geklärt sind, teile den Rest deines Debuggings in diese beiden Pfade auf.

Moderations- und Inhaltsrichtlinienfehler bei der Videogenerierung

Sicherheitssperren können an drei verschiedenen Punkten auftreten: bevor die Generierung startet (die Anfrage wird sofort abgelehnt), während des Renderns (der Job wird mittendrin gestoppt) oder nachdem das Video erzeugt wurde (die Ausgabe wird vor der Auslieferung gefiltert) ^[11]. Dieser letzte Fall bringt Leute durcheinander. Ein Job kann fertig werden und trotzdem nichts liefern, wenn das Ergebnis gefiltert wird.

Bei Polling-basierten APIs kann der HTTP-Status irreführend sein. Du erhältst vielleicht 200 OK von der Statusabfrage, während der JSON-Body state: "failed" meldet und einen Fehler wie SensitiveContentDetected oder NSFW enthält ^[12]. In der Praxis ist der Polling-Body die maßgebliche Quelle, nicht der HTTP-Statuscode.

Wenn eine Moderationssperre ausgelöst wird, versuche nicht denselben Prompt erneut. Schreibe ihn um. Einfache, technische Kameraführungs-Formulierungen können helfen, Falsch-Positive strenger Sicherheitsfilter zu reduzieren ^[11]. Zum Beispiel:

• gimbal shot
• medium tracking shot
• golden hour lighting

Es gibt hier noch eine Feinheit. Manche Modelle, darunter Google Veo, geben möglicherweise weniger Clips zurück als angefordert, wenn einige Ausgaben von Sicherheitsfiltern blockiert werden, anstatt den ganzen Job scheitern zu lassen ^[3]. Prüfe also nicht nur, ob die Anfrage abgeschlossen wurde. Prüfe, ob die Anzahl der zurückgegebenen Assets mit der angeforderten Anzahl übereinstimmt.

Wenn der Prompt sauber aussieht und der Job trotzdem fehlschlägt, geht es zur nächsten Ebene: Serverstabilität.

500-, 502-, 503- und Timeout-Fehler bei asynchronen Video-Jobs

Serverseitige Fehler sitzen an einer anderen Stelle des Debugging-Ablaufs. Text-to-Video-Jobs belegen oft 30–90 Sekunden lang einen GPU-Slot ^[3], was sie anfälliger für Überlastung und Timeouts macht.

Prüfe bei 500- und 504-Fehlern den Job-Status, bevor du einen Retry durchführst. Blinde Retries können doppelte Renderings erzeugen und deine Kosten verdoppeln ^[3]. Protokolliere jede taskId oder prediction_id, damit du den Status-Endpunkt direkt abfragen kannst, bevor du einen neuen Job absendest ^[3][13].

Wenn Retries sicher sind, verwende exponentielles Backoff mit Jitter. Ein praktisches Setup ist:

• bei 5 Sekunden beginnen
• bei 60 Sekunden deckeln
• nach 3 Versuchen aufhören ^[13][12]

Setze Client-Timeouts auf 10 Minuten oder mehr ^[3] und richte Alarme bei steigenden predict_time-Werten ein ^[3].

Ein Schritt-für-Schritt-Debugging-Workflow für Text-to-Video-APIs

Fehler klassifizieren, dann die richtige Lösung anwenden

Verwende diesen Workflow, um in einem Durchgang vom Symptom zur Lösung zu gelangen. Lies zuerst den vollständigen Response-Body. Sortiere dann den Fehler nach HTTP-Statuscode und dem, was der Fehler-Body sagt. Manche Anbieter senden auch interne Fehlerbereiche, aber dein Hauptleitfaden sollten der HTTP-Statuscode und der Fehler-Body sein ^[3][1].

Beginne mit dem Response-Body und ordne das Ergebnis dann einer dieser Gruppen zu:

Sobald ein Job abgesendet wurde, höre auf, nur in HTTP-Antworten zu denken, und schau dir auch den Task-Status an. Prüfe bei asynchronen Jobs die Polling-Antwort auf failed oder expired, bevor du denselben Job erneut sendest. Dieser eine Schritt kann dir zusätzliche Kosten und viel Verwirrung ersparen.

Bevor du den Code anfasst, prüfe die Statusseite des Anbieters. Wenn der Dienst beeinträchtigt ist, sagt dir lokales Debugging nicht viel. Untersuche danach die x-deny-reason-Response-Header. Ablehnungen auf Proxy-Ebene können wie Modellfehler aussehen, wenn du diese Prüfung überspringst ^[3].

Fixiere außerdem genaue Modellversions-Strings wie kling-v3.0-std statt latest. Ein stilles Modell-Update kann neue Validierungsfehler in eine Pipeline einbringen, die am Vortag noch einwandfrei funktioniert hat ^[3].

Wichtige Erkenntnisse für zuverlässigere Integrationen

Die meisten Fehler bei Text-to-Video-APIs folgen einigen wiederkehrenden Mustern. Wenn du einen 4xx-Fehler erhältst, musst du die Anfrage, die Zugangsdaten oder das Setup ändern. Denselben Aufruf erneut zu senden behebt meist nichts.

• Anfrage-Eingaben protokollieren: Modell-ID, Prompt-Hash und Parameter (siehe unsere KI-API-Tutorials für Best Practices beim Logging).
• Task-ID, finalen Status, predict_time und die vollständige Fehlermeldung protokollieren.
• Nur 429 und 5xx nach Prüfung des Task-Status erneut versuchen, um doppelte Renderings und verdoppelte Kosten zu vermeiden ^[3].
• predict_time auf Ausschläge beobachten — sie können frühzeitig auf eine Verschlechterung der Infrastruktur hinweisen ^[3].

FAQs

Woher weiß ich, ob ein Video-Job tatsächlich fehlgeschlagen ist?

Frage den Task-Status-Endpunkt mit der Task-ID ab, die du beim Absenden des Jobs erhalten hast. Wenn das status-Feld als failed zurückkommt, ist der Job nicht durchgelaufen.

Schau als Nächstes auf das error-Feld in der Antwort. Das sagt dir, warum es fehlgeschlagen ist, sodass du über das weitere Vorgehen entscheiden kannst:

• deinen Prompt anpassen
• dein Kontoguthaben prüfen
• warten, falls ein Infrastrukturproblem vorliegt

Du kannst auch Webhooks verwenden, um automatische Benachrichtigungen zu erhalten, wenn ein Job in den Zustand „failed“ übergeht.

Wann sollte ich eine Text-to-Video-API-Anfrage erneut versuchen?

Versuche transiente Fehler wie 429-Ratenlimits und 500-serverseitige Probleme mit exponentiellem Backoff erneut. Das verlangsamt wiederholte Versuche und hilft dir, das System nicht zu überlasten.

Prüfe bei einem 504 Gateway Timeout oder einem Task-Fehler den Task-Status, bevor du es erneut versuchst. Ein blinder Retry kann doppelte Renderings auslösen und zusätzliche Kosten verursachen.

Versuche 400- oder 401-Fehler nicht erneut. Diese bedeuten meist, dass die Anfrage selbst zuerst korrigiert werden muss.

Warum sollte ein Prompt nach dem Absenden blockiert werden?

Ein Prompt wird meist blockiert, weil er gegen die Sicherheits- oder Moderationsregeln eines Anbieters verstößt. Das kann direkt beim Absenden passieren oder später während der Generierung, wenn das System verbotene visuelle oder Audio-Inhalte erkennt.

Häufige Auslöser sind sensible Themen, Gewalt, Minderjährige oder urheberrechtlich geschütztes Material. Und weil Moderationssysteme dazu neigen, auf Nummer sicher zu gehen, können selbst harmlose Prompts markiert werden.

Wenn das passiert, schreibe die Anfrage in neutralerer, beschreibender Sprache um.