Fehlerbehandlung

Einheitliches Fehlerantwortformat

Alle API-Fehler geben ein einheitliches JSON-Format zurück:

JSON

{
  "code": 2010,
  "status": "error",
  "message": "You don't have enough credit to create this task",
  "suggestion": "Please purchase more credit",
  "request_id": "req_abc123"
}

Feld	Typ	Beschreibung
code	ganze Zahl	Fehlercode
status	Zeichenfolge	Ergebnis der Anfrage; `error`, wenn die Anfrage fehlschlägt
message	Zeichenfolge	Fehlerbeschreibung
suggestion	Zeichenfolge	Vorgeschlagene Lösung
request_id	Zeichenfolge	Eindeutige Anforderungskennung zur Fehlerbehebung

HTTP Statuscodes

Statuscode	Bedeutung	Beschreibung
200	Erfolg	Die Anfrage wurde erfolgreich bearbeitet
400	Ungültige Parameter	Erforderliche Parameter fehlen oder sind fehlerhaft
401	Nicht authentifiziert	Der API Key fehlt oder ist ungültig
403	Unzureichende Berechtigungen	Sie haben keine Berechtigung zum Zugriff auf die Ressource oder Ihr Guthaben reicht nicht aus
404	Ressource nicht gefunden	Die angeforderte Aufgabe oder Ressource existiert nicht
429	Zu viele Anfragen	Ratenlimit oder Parallelitätslimit überschritten. Reduzieren Sie die Häufigkeit Ihrer Anfragen oder versuchen Sie es später erneut
500	Servicefehler	Interner Serverfehler. Versuchen Sie es später noch einmal

Fehlercode-Referenz

Fehlercode	Bedeutung	Empfohlene Handhabung
1000	Ungültiges API Key	Überprüfen Sie, ob API Key korrekt ist oder gelöscht wurde
1001	Nicht autorisiert	Überprüfen Sie, ob der Anforderungsheader `Authorization` enthält
1007	Ratenlimit überschritten	Reduzieren Sie die Anforderungshäufigkeit und implementieren Sie Wiederholungsversuche mit exponentiellem Backoff
2000	Parallelitätslimit überschritten	Warten Sie, bis eine Aufgabe derselben Kategorie abgeschlossen ist, bevor Sie weitere erstellen, oder warten Sie die im Antwortheader `Retry-After` angegebene Zeit ab. Siehe Ratenbeschränkungen
2002	Nicht unterstützter Anforderungsparameter	Überprüfen Sie, ob die Feldnamen und Werte des Anforderungstexts mit der Dokumentation übereinstimmen
2003	Leere Eingabedatei	Stellen Sie sicher, dass die hochgeladene Datei nicht leer ist und ein gültiges Format verwendet
2004	Nicht unterstützter Dateityp	Überprüfen Sie, ob das Dateiformat in der unterstützten Liste enthalten ist
2008	Verstoß gegen die Inhaltsrichtlinien	Ändern Sie den Eingabeinhalt, um verbotene Wörter oder Bilder zu vermeiden
2010	Unzureichende Credits	Guthaben in der Konsole aufladen
2015	Version veraltet	Aktualisieren Sie auf die neueste API-Version
2018	Modell zu komplex	Reduzieren Sie die Komplexität oder Polycount des Eingabemodells

Beispiele für die Fehlerbehandlung

import time
import requests

def call_api_with_retry(url, headers, payload=None, max_retries=3):
    for attempt in range(max_retries):
        if payload:
            response = requests.post(url, headers=headers, json=payload)
        else:
            response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            wait = 2 ** attempt
            print(f"Rate limit triggered. Retrying in {wait} seconds...")
            time.sleep(wait)
            continue

        error = response.json()
        raise Exception(
            f"API error [{error['code']}]: {error['message']} "
            f"(suggestion: {error.get('suggestion', 'none')})"
        )

    raise Exception("Maximum retry attempts exhausted")

async function callApiWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return await response.json();
    }

    if (response.status === 429) {
      const wait = 2 ** attempt * 1000;
      console.log(`Rate limit triggered. Retrying in ${wait / 1000} seconds...`);
      await new Promise(resolve => setTimeout(resolve, wait));
      continue;
    }

    const error = await response.json();
    throw new Error(
      `API error [${error.code}]: ${error.message} (suggestion: ${error.suggestion || "none"})`
    );
  }

  throw new Error("Maximum retry attempts exhausted");
}

Empfehlungen zur Wiederholungsstrategie

Für wiederholbare Fehler, wie etwa 429 Ratenlimits und 500 Dienstfehler, verwenden Sie eine exponentielle Backoff-Strategie:

Erster Wiederholungsversuch: 1 Sekunde warten
Zweiter Wiederholungsversuch: 2 Sekunden warten
Dritter Wiederholungsversuch: 4 Sekunden warten
Behalten Sie die maximale Anzahl an Wiederholungsversuchen bei 5 oder weniger

Bei nicht wiederholbaren Fehlern wie 400, 401 und 403 lösen Sie direkt eine Ausnahme aus und beheben das zugrunde liegende Problem.