Fehler bei der Kling-API lassen sich grob in drei Ebenen teilen: Anfrageebene (HTTP-Status und Geschäftscode), Aufgabenebene (task failed) und Ergebnissebene (Download fehlgeschlagen). Die Reihenfolge der Untersuchung sollte sein: zuerst Status- und Geschäftscode, dann request_id und minimale Reproduktion, erst zuletzt Parameter ändern oder das Modell wechseln. Umgekehrt wird ein Konfigurationsproblem leicht als Modellschwäche fehlgedeutet.

Dieser Beitrag verwendet die Fehlercodes und Aufgabenstatus der Kling-Dokumentation von Oktober 2026 als Beispiel und gibt eine Prüfreihenfolge sowie Empfehlungen zu Wiederholung und Idempotenz. Schnittstellen und Codes können sich mit Versionen ändern; maßgeblich ist die offizielle Dokumentation.

Hinweis: Kling ist eine Marke von Kuaishou und verbundenen Unternehmen. Dieser Beitrag dient der technischen Erläuterung und impliziert keine Zugehörigkeit oder Empfehlung. Fehlercodes, Parallelitätsregeln und Abrechnung richten sich nach der offiziellen Dokumentation und der Preisseite dieser Website.

1. Zuerst drei Fehlerebenen unterscheiden

Fehler der Anfrageebene kommen sofort zurück: 401 Authentifizierung, 400 Parameter, 403 Berechtigung, 429 Drosselung oder Guthaben, 5xx Serverfehler. Fehler der Aufgabenebene treten nach erfolgreichem Senden und Erhalt der Aufgaben-ID auf: Der Status wechselt auf failed, der Grund steht im message-Feld. Fehler der Ergebnissebene bedeuten, dass die Aufgabe bereits succeeded ist, der Downloadlink aber nicht erreichbar, abgelaufen oder bereinigt ist.

Die drei Ebenen getrennt protokollieren. Eine fehlgeschlagene Aufgabe als Authentifizierungsfehler zu behandeln und Keys zu tauschen, oder einen Downloadfehler als Generierungsfehler zu werten und erneut zu senden, kostet Zeit und Geld.

2. 401 Authentifizierung: 1000–1004 einzeln prüfen

401 bedeutet, dass die Identität nicht verifiziert wurde, und hat meist nichts mit Modellfähigkeit oder Guthaben zu tun. Die Dokumentation nennt: 1000 Authentifizierung fehlgeschlagen, 1001 fehlendes Authorization-Feld, 1002 ungültiges Token, 1003 Token noch nicht gültig, 1004 Token abgelaufen.

Aktuelle Modelle verwenden einen API-Key im Header Authorization: Bearer; die alte Schnittstelle signiert mit AK/SK ein JWT (HS256, etwa 30 Minuten gültig). Beide Verfahren nicht vermischen. Prüfreihenfolge:

  1. Lautet der Header Authorization: Bearer <Zugangsdaten>, und steht nach Bearer ein Leerzeichen?
  2. Enthält der Key Leerzeichen, Zeilenumbrüche oder zusätzliche Anführungszeichen? Beim Kopieren aus Chatfenstern passiert das leicht.
  3. Wird die Umgebungsvariable tatsächlich geladen? Zur Kontrolle nur das Präfix ausgeben, nie den vollständigen Key.
  4. Wurde der Key gelöscht, rotiert oder deaktiviert? Ist ein JWT der alten Schnittstelle älter als 30 Minuten, oder verhindert eine Zeitabweichung die Gültigkeit?
  5. Gehören Base URL, Regionsdomain und Key zur selben Plattform? Auslandsserver und Inlandsplattform nicht mit denselben Adressen mischen.
  6. Überschreibt oder verwirft ein Reverse Proxy den Authorization-Header? Ist der Callback-Signaturschlüssel korrekt konfiguriert?
  7. Mit einem neuen Key eine minimale Anfrage senden, um Key-Probleme von Proxy- oder Gateway-Konfiguration zu trennen.

3. 429, Guthaben und Parallelität: zuerst den Drosselungstyp klären

429 bedeutet nicht immer „zu schnell“. In der Kling-Dokumentation steht 1100 für anormalen Kontostatus, 1101 für Postpaid-Rückstand und 1102 für aufgebrauchtes oder abgelaufenes Prepaid-Paket; alle drei laufen unter 429. 1302 ist die Ratenbegrenzung, 1303 die Überschreitung der Paket-Parallelität, 1304 eine IP-Whitelist-Beschränkung; 1103 ist dagegen 403 ohne Berechtigung.

Die Parallelität wird nach Konto, Modellversion und Pakettyp getrennt berechnet; alle Keys eines Kontos teilen das Kontingent. Eine Aufgabe belegt ab submitted einen Slot bis Erfolg oder Fehler; Abfragen belegen keinen Slot. Weitere Keys umgehen das Limit daher nicht.

Vorgehen: zuerst message und Geschäftscode lesen und zwischen Guthaben, Parallelität und Berechtigung unterscheiden. Bei 1302 und 1303 exponentielles Backoff mit mindestens 1 Sekunde Erstwartezeit und Sendung über eine Queue. Bei anhaltender Überschreitung Parallelität senken, Last zeitlich verteilen oder das Paket an den tatsächlichen Bedarf anpassen. Keine Wiederholungswelle ohne Backoff gegen das Limit fahren.

4. 400/404 Parameter- und Modellfehler: 1200–1203

1200 ist ein allgemeiner Parameterfehler, 1201 ein konkreter Feld- oder Wertfehler, 1202 eine falsche HTTP-Methode, 1203 eine nicht vorhandene Ressource oder ein nicht vorhandenes Modell. 1300 bedeutet Konflikt mit Plattformrichtlinien, 1301 eine Inhaltsrichtlinienverletzung der Eingabe, meist ebenfalls 400.

Häufige Ursachen: Dauer außerhalb des Modellbereichs (2.5 Turbo nur 5 oder 10 Sekunden, 3.0-Serie 3–15 Sekunden); nicht unterstützte Auflösung (4K nur bei einigen Modellen); Seitenverhältnis, Start-/Endbild oder Anzahl Referenzbilder passen nicht zum Modell; Bild-URL für die Plattform nicht erreichbar; Modellversion fehlt im Pfad oder in model_name; Prompt überschreitet die Längenbegrenzung.

Bei der Fehlersuche zuerst mit einer minimalen Anfrage reproduzieren, dann Parameter einzeln wieder ergänzen. Eine Ablehnung durch die Inhaltsprüfung ist kein technischer Fehler; nicht durch wiederholtes Umformulieren von Schlüsselwörtern umgehen.

5. Task failed: Status, message und Callback

Übliche Aufgabenstatus sind submitted, processing, succeeded, failed; die alte Schnittstelle kann succeed statt succeeded liefern, die Adapterschicht muss beides unterstützen. Bei failed sind message, request_id und die Sendeparameter entscheidend.

Häufige Gründe: Eingabebild oder -video nicht herunterladbar, Inhaltsprüfung, Upstream-Renderingfehler, Aufgaben-Timeout, vorübergehende Modellunanfrage. Fehlgeschlagene Aufgaben dokumentieren und nicht sofort löschen, sonst ist keine Nachanalyse möglich.

Bei Nutzung von callback_url die Header webhook-id, webhook-timestamp und webhook-signature prüfen; die Signatur verwendet HMAC-SHA256. Test-Callbacks sind höchstens alle 6 Sekunden erlaubt; eine erfolgreiche serverseitige Verarbeitung soll HTTP 200 zurückgeben. Die Dokumentation verspricht keine zugesagte Wiederholung fehlgeschlagener Callbacks; daher in der Produktion Polling als Rückfall behalten und sich nicht allein auf Callbacks verlassen.

6. Timeouts und Polling: asynchrone Aufgaben nicht synchron schreiben

Videoaufgaben dauern oft zwischen einigen Dutzend Sekunden und mehreren Minuten, zu Spitzenzeiten mit Warteschlange. Verbindungs-Timeout, Lese-Timeout und Gesamt-Timeout des HTTP-Clients getrennt setzen: Verbindung kurz, Lese-Timeout passend zur Abfrageschnittstelle, Gesamt-Timeout nach akzeptabler Geschäftszeit.

Polling beginnt bei 5 Sekunden und geht schrittweise auf 15–30 Sekunden mit zufälligem Jitter; maximale Anzahl und Endzeitpunkt festlegen. Nach Ablauf als „zu bestätigen“ markieren statt endlos zu warten. Bei 5xx stehen 5000, 5001 und 5002 für internen Fehler, vorübergehende Nichtverfügbarkeit und Upstream-Timeout; diese dürfen mit Backoff wiederholt werden. 401, 403 und 1301 nicht blind wiederholen.

Das folgende vereinfachte Python-Beispiel verbindet Senden, Polling, Fehlerklassifikation und Download:

import time
import random
import requests

API_KEY = "ihre-kling-zugangsdaten"
BASE = "https://ihre-kling-schnittstelle"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task(payload, external_id):
    payload = {**payload, "external_task_id": external_id}
    resp = requests.post(f"{BASE}/text-to-video/ihr-modellpfad",
                         json=payload, headers=HEADERS, timeout=(5, 30))
    if resp.status_code == 401:
        raise RuntimeError("Authentifizierung fehlgeschlagen: Key, Bearer und Region prüfen")
    if resp.status_code == 429:
        raise RuntimeError(f"Drosselung, Guthaben oder Parallelität: {resp.text}")
    resp.raise_for_status()
    return resp.json()["data"]["id"]

def wait_and_download(task_id, timeout=900):
    deadline = time.time() + timeout
    delay = 5
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks", params={"task_ids": task_id},
                         headers=HEADERS, timeout=(5, 30))
        if r.status_code in (500, 503, 504):
            time.sleep(delay + random.random())
            delay = min(delay * 1.5, 30)
            continue
        r.raise_for_status()
        task = r.json()["data"][0]
        status = task["status"].lower()
        if status in ("succeeded", "succeed"):
            url = task["outputs"][0]["url"]
            video = requests.get(url, timeout=(5, 120))
            video.raise_for_status()
            return video.content  # In der Produktion streaming in den Objektspeicher schreiben
        if status == "failed":
            raise RuntimeError(task.get("message") or "task failed")
        time.sleep(delay)
        delay = min(delay * 1.5, 30)
    raise TimeoutError(task_id)

# Vor erneutem Senden zuerst über external_task_ids prüfen, ob die Aufgabe bereits existiert

7. Downloadfehler: Linklaufzeit und Übertragung

Nach Erfolg steht das Ergebnis in outputs; das Video enthält url, watermark_url und duration. Laut Dokumentation werden Ergebnisse nach 30 Tagen bereinigt, und die tatsächliche Linklaufzeit kann kürzer sein. Downloadfehler entstehen häufig durch abgelaufene Links, bereinigte Ergebnisse, Netzwerk-Timeouts, Objektspeicherrechte oder Proxy-Blockierung.

Empfehlung: Nach Erfolg sofort herunterladen und in den eigenen Objektspeicher übertragen; Download und Generierung getrennt wiederholen, bei Downloadfehler nicht neu generieren; content-type, content-length und Prüfsumme protokollieren; vollständige signierte Links nicht in öffentliche Logs schreiben. Ist das Ergebnis bereits bereinigt, bleibt meist nur eine neue Generierung; die Übertragung gehört daher unmittelbar nach Erfolgscallback oder erfolgreichem Polling.

8. Wiederholung und Idempotenz: eine Störung nicht doppelt bezahlen

Vor der Wiederholung klassifizieren: 429, 5xx und Netzwerk-Timeouts dürfen mit Backoff wiederholt werden; 400, 401, 403 und 1301 zuerst beheben; bei failed zuerst message lesen und die Ursache beheben, dann eine neue Aufgabe senden.

Kling unterstützt external_task_id und verlangt Eindeutigkeit innerhalb eines Kontos. Beim Senden die Geschäftsnummer oder den Idempotenzschlüssel mitgeben; nach einem Netzwerk-Timeout zuerst über external_task_ids prüfen, ob die Aufgabe existiert, und dann über eine erneute Sendung entscheiden. Sonst wird aus einem Timeout schnell zwei Aufgaben und zwei Abbuchungen.

Die Aufgabentabelle sollte mindestens erfassen: Geschäftsnummer, task_id, external_id, Modell und Parameter, Status, message, request_id, Kosten und Wiederholungszahl. Beim Abgleich nach task_id deduplizieren, nicht nach Sendevorgängen zählen.

9. Übersicht der Prüfreihenfolge

Symptom Zuerst prüfen Häufige Ursache Behandlung
401 Authorization, Key, Region 1000–1004, JWT abgelaufen oder noch nicht gültig Zugangsdaten korrigieren, minimale Anfrage
429 Geschäftscode und message 1101/1102 Guthaben, 1302 Rate, 1303 Parallelität Aufladen, Backoff, Parallelität senken
400 Parameter und Inhalt 1200/1201/1300/1301 Parameter nach message korrigieren, Prüfungsablehnung nicht umgehen
404 Pfad, Methode, Modell 1202/1203 Pfad und Modellnamen anhand der Dokumentation ändern
failed message, Eingabematerial Downloadfehler, Prüfung, Renderingfehler Material oder Parameter korrigieren, Datensatz behalten
Timeout Verbindungs-/Lese-/Gesamt-Timeout Warteschlange, lange Aufgaben, Upstream-5xx Timeouts getrennt setzen, Backoff-Polling
Downloadfehler Linkstatus und Laufzeit abgelaufen, bereinigt, Netzwerk Sofort übertragen, Download separat wiederholen

Häufige Fragen

Bedeutet 429 zu wenig Guthaben?

Nicht unbedingt. Unter 429 können 1101 Rückstand, 1102 aufgebrauchtes Paket, aber auch 1302 Ratenlimit, 1303 Parallelitätsüberschreitung oder 1304 IP-Limit stehen. Zuerst Geschäftscode und message lesen, dann über Aufladen, Backoff oder Parallelitätssenkung entscheiden.

Werden fehlgeschlagene Aufgaben berechnet?

Das hängt von den Plattformregeln und dem Fehlergrund ab. Vor der Einbindung klären, wie Fehler, Prüfungsablehnung und Timeout-Abbruch abgerechnet werden, und die Rechnung prüfen. Nicht annehmen, dass Fehler grundsätzlich kostenlos sind.

Wie oft sollte gepollt werden?

Start bei 5 Sekunden, schrittweise Backoff auf 15–30 Sekunden, mit zufälligem Jitter. Eine Endzeit und maximale Anzahl setzen, um endloses Warten und hohe Last auf der Abfrageschnittstelle zu vermeiden.

Was tun, wenn kein Callback ankommt?

Zuerst prüfen, ob die Callback-Adresse öffentlich erreichbar ist, HTTP 200 zurückgibt und die Signaturprüfung besteht, dann, ob der Zeitstempel im erlaubten Fenster liegt. Die Dokumentation verspricht keine zugesagte Wiederholung; in der Produktion Polling als Rückfall behalten.

Zuerst prüfen, ob der Aufgabenstatus succeeded ist und ob der Link abgelaufen oder das Ergebnis bereinigt wurde. Nach Erfolg sofort in den Objektspeicher übertragen; nach Ablauf bleibt meist nur eine neue Generierung.

Nächster Schritt

Zuerst im ZSQH AI Gateway einen Test-Key erstellen und 401, 429, Parameterfehler, Task-Fehler und Timeout je einmal durchspielen, dann das Produktionsmonitoring anbinden. Verfügbare Modelle und Abrechnung richten sich nach den Modellpreisen.

Weiterlesen: