Fehler

Die API verwendet die üblichen HTTP-Statuscodes: 2xx bedeutet Erfolg, 4xx, dass die Anfrage geändert werden muss, und 5xx einen Fehler auf unserer Seite oder bei der Verarbeitung. Alle Fehlerantworten haben dieselbe JSON-Struktur und lassen sich einheitlich behandeln.

Fehlerformat#

{
  "error": {
    "code": "invalid_request",
    "message": "\"resolution\" must be one of: 480p, 720p",
    "param": "resolution"
  }
}

• code – eine stabile, maschinenlesbare Zeichenfolge. Verwenden Sie diese für die Fallunterscheidung, nicht den Meldungstext.
• message – eine verständliche Erklärung, die Sie protokollieren können. Die Formulierung kann sich ändern.
• param – vorhanden, wenn ein bestimmtes Anfragefeld den Fehler verursacht hat.

Fehlercodes#

Fehler innerhalb einer Generierung#

Ein HTTP-Fehler bedeutet, dass die Anfrage selbst abgelehnt wurde und nichts berechnet wurde. Anders ist es, wenn eine angenommene Generierung später fehlschlägt: Der API-Aufruf war erfolgreich (auch wenn POST /run bei einem sofortigen Fehlschlag 202 zurückgibt); der Status der Generierung status wird zu failed, mit einem Fehlerobjekt error. Die Reservierung wird automatisch erstattet. Dasselbe Objekt finden Sie in GET /generations, der Webhook-Nutzlast und den MCP-Tool-Ergebnissen.

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "ByteDance's safety review for Seedance 2.0 Fast rejected this request (the prompt or an input file).",
    "reason": "content_blocked",
    "hint": "Describe the character's look instead of naming a copyrighted character or real person, keep it non-explicit, or try another model.",
    "retryable": false,
    "refunded": true,
    "detail": "Ihre Anfrage hat die Inhaltsprüfung nicht bestanden. Passen Sie den Prompt an und versuchen Sie es erneut."
  }
}

code ist die übergeordnete Fehlerklasse (die vier seit dem Start dokumentierten Werte). reason nennt genau den Grund. Verwenden Sie diesen Wert für die Fallunterscheidung und zeigen Sie message sowie hint Ihren Nutzern. retryable gibt an, ob dieselbe Anfrage bei erneutem Senden erfolgreich sein kann; param nennt, sofern erkennbar, das zu ändernde Feld; detail enthält den Wortlaut des Modellanbieters.

Durch Ihre Anfrage verursachte Fehler – content_blocked, eine abgelehnte Datei unter invalid_input, input_unreachable – werden nicht über andere Anbieter erneut versucht, da sie wieder abgelehnt würden. Bei Ausfällen und Modellfehlern wird zuerst über alle geeigneten Routen zum selben Preis erneut versucht. Siehe Fehler und Erstattungen.

Wenn ein Anbieter meldet, dass er eine Ihrer Eingabedateien nicht herunterladen kann, versuchen wir normalerweise, sie selbst herunterzuladen. Wenn das klappt, wird der Auftrag mit einer von uns gehosteten Kopie erneut gestartet — zum selben Preis, ohne dass Sie etwas ändern müssen. In der Generierung werden weiterhin die von Ihnen gesendeten URLs angezeigt, und die Kopie wird zusammen mit der Generierung gemäß ihrer Aufbewahrungsfrist gelöscht. input_unreachable bedeutet daher meist, dass die Datei gar nicht heruntergeladen werden konnte: Es ist eine Anmeldung erforderlich, der signierte Link ist abgelaufen, er verweist nicht direkt auf die Datei oder der Host hat die Anfrage abgelehnt. Wir kopieren Bilder bis zu 30 MB, Videos bis zu 200 MB und Audiodateien bis zu 50 MB. Größere oder nicht lesbare Dateien schlagen mit invalid_input fehl.

Sicher erneut versuchen#

Versuchen Sie 429, 500, 502 und 503 mit exponentiellem Backoff und Zufallsstreuung erneut. Andere 4xx-Fehler nicht unverändert wiederholen – sie würden auf dieselbe Weise scheitern.

const RETRYABLE = new Set([429, 500, 502, 503]);

export async function postWithRetry(url, headers, body, attempts = 5) {
  let resp;
  for (let attempt = 0; attempt < attempts; attempt++) {
    resp = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
    if (!RETRYABLE.has(resp.status)) break;
    // exponential backoff with jitter: ~1s, 2s, 4s, 8s…
    await new Promise((r) => setTimeout(r, Math.min(2 ** attempt, 30) * 1000 + Math.random() * 1000));
  }
  const data = await resp.json();
  if (!resp.ok) throw new Error(`${resp.status} ${data.error.code}: ${data.error.message}`);
  return data;
}

import random, time, requests

RETRYABLE = {429, 500, 502, 503}

def post_with_retry(url, headers, json, attempts=5):
    for attempt in range(attempts):
        resp = requests.post(url, headers=headers, json=json, timeout=30)
        if resp.status_code not in RETRYABLE:
            break
        # exponential backoff with jitter: ~1s, 2s, 4s, 8s…
        time.sleep(min(2 ** attempt, 30) + random.random())
    if not resp.ok:
        err = resp.json()["error"]
        raise RuntimeError(f"{resp.status_code} {err['code']}: {err['message']}")
    return resp.json()

Beispiele für Validierungen#

Validierungsmeldungen nennen das Feld und die zulässigen Werte. Sie können Entwicklern daher unverändert angezeigt werden:

[
  {
    "error": {
      "code": "invalid_request",
      "message": "\"prompt\" is required",
      "param": "prompt"
    }
  },
  {
    "error": {
      "code": "invalid_request",
      "message": "Unknown parameter \"resoluton\"",
      "param": "resoluton"
    }
  },
  {
    "error": {
      "code": "not_found",
      "message": "Unknown endpoint \"bytedance/seedance-2.0-fast/text-to-gif\". See GET /api/v1/models."
    }
  }
]

Sie können eine Anfrage auch bepreisen, ohne sie auszuführen: POST /api/v1/quote/{endpoint} prüft die preisrelevanten Felder und gibt die Kosten zurück. Siehe API-Referenz.