Fehler

Die Reigniter API verwendet Standard-HTTP-Statuscodes. Jede Fehlerantwort ist JSON.

Fehlerkörper

Die meisten Fehler sehen so aus:

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "retryAfter": 37
}

Spielfeld	Immer präsent	Was es ist
`error`	Ja	Eine Nachricht, die du einer Person zeigen kannst. Sie kann sich in der Formulierung ändern, also passt nicht darauf.
`code`	Die meisten Fehler	Ein stabiler, großgeschriebener Code. Verzweig das hier.
`details`	Einige Fehler	Zusätzlicher Kontext, zum Beispiel `retryAfter` oder Nutzungszahlen.
`retryAfter`	Einige `429`s	Sekunden, um zu warten, bevor ich es erneut versuchen kann.

Einige Fehler haben keine code, wie 404 Job not found und 403 Forbidden. Verzweigte auf dem Status für diese.

Validierungsfehler

Wenn der Anforderungskörper nicht mit dem Schema übereinstimmt, erhält man 400 mit einer detail Zeichenkette, die jedes Problem als field: message auflistet:

{
  "error": "Validation failed",
  "detail": "aspect: Invalid option: expected one of \"9:16\"|\"16:9\"|\"1:1\"|\"4:5\"|\"4:3\"|\"3:4\""
}

Statuscodes

Status	Bedeutung	Was zu tun ist
`200`	Erfolg.
`201`	Erstellt (Webhooks).
`202`	Angenommen. Das Rendern hat begonnen.	Frag nach dem Job oder warte auf den Webhook.
`400`	Der Antrag wurde abgelehnt. Es wurde nichts berechnet.	Beheben Sie die Anfrage. Versuchen Sie es nicht unverändert.
`401`	Fehlt, ist ungültig oder API Schlüssel widerrufen.	Überprüfe den Schlüssel.
`402`	Problem mit Plan, Credit oder Nutzung.	Lies `code`.
`403`	Ein ausgesetztes Konto oder ein Job, der nicht dir gehört.	Kontaktiere den Support oder schau dir die Job-ID an.
`404`	Nicht gefunden.	Überprüfe den Ausweis oder den Weg.
`409`	Doppelte Anfrage oder Limit erreicht.	Lies `code`.
`413`	Dieses Rendern würde mehr kosten als das Render-Limit.	Verwenden Sie weniger Szenen oder einen niedrigeren `quality`.
`422`	Das Render hat keine Marke, kein Produkt oder einen Moderator, der es verankert.	Siehe Videos machen.
`429`	Zu viele Anfragen oder zu viele Renderings auf einmal.	Warte und versuch es erneut. Sieh Grenzen.
`500`	Bei uns ist etwas schiefgelaufen.	Versuchen Sie es später nochmal.
`502`	Die Planung aus deinem Briefing ist gescheitert. Die Planungsgutschriften wurden zurückerstattet.	Versuchen Sie es erneut oder formulieren Sie das Briefing um.
`503`	Die Bereitstellung ist pausiert oder ein Service ist ausgefallen. Es wurde nichts berechnet.	Versuchen Sie es später nochmal.

Ein unbekannter Pfad unter /v1/ kehrt 404 mit code: "NOT_FOUND" zurück.

Fehlercodes

Authentifizierung und Plan

Code	Status	Bedeutung
`NO_API_KEY`	401	Kein `Authorization` Header, sonst beginnt der Token nicht mit `emp_`.
`INVALID_API_KEY`	401	Der Schlüssel ist unbekannt oder widerrufen.
`PLAN_UPGRADE_REQUIRED`	402	API Zugang benötigt den Agency Plan.
`ACCOUNT_SUSPENDED`	403	Das Konto ist gesperrt.

Credits und Verwendung

Code	Status	Bedeutung
`NO_CREDITS`	402	Das Konto hat keine Guthaben mehr.
`INSUFFICIENT_CREDITS`	402	Nicht genug Credits für dieses Rendering.
`ABUSE_CAP_EXCEEDED`	402	Das monatliche Nutzungslimit für den Plan ist erreicht.
`STORAGE_FULL`	402	Die Videobibliothek des Kontos ist voll. Entferne einige Videos.
`UPGRADE_REQUIRED`	402	Video benötigt einen kostenpflichtigen Tarif.
`REQUEST_COST_TOO_HIGH`	413	Dieses eine Rendering würde mehr kosten als das Pro-Render-Limit.

Siehe Konto und Abrechnung für Credits und Pläne.

Renderanfragen

Code	Status	Bedeutung
`CONTENT_BLOCKED`	400	Das Briefing oder eine Szene bricht gegen die Inhaltsregeln.
`PRODUCT_IMAGE_REQUIRED`	400	Dieses Format benötigt `product_image_url`, oder `product_enabled: false`.
`PRESENTER_REQUIRED`	400	Eine Sprechszene hat kein Gesicht. Füge `avatar_preset_id` hinzu oder schick `presenter_enabled: false`.
`UNSUPPORTED_MODEL`	400	Eine Szene verlangt ein Render-Modell, das Reigniter nicht verwenden kann.
`BRAND_REQUIRED`	422	Es wurde nach einer Marke gefragt, aber keine konnte gefunden werden. Schick `brand_logo_url`.
`NO_ANCHOR`	422	Kein Marken-, Produktfoto oder Präsentierender. Fügen Sie eines hinzu oder melden Sie sich ab.
`CANVAS_NOT_FOUND`	404	Ein referenziertes Projekt befindet sich nicht auf diesem Konto.
`DUPLICATE_REQUEST`	409	Dieses `Idempotency-Key` war bereits benutzt. Nichts Neues wurde berechnet.
`PLAN_FAILED`	502	Die Planung aus dem Briefing scheiterte. Die Planungsgutschriften wurden zurückerstattet.

Bei einem brief kann ein wiederholtes Idempotency-Key auch als 402 mit der Nachricht This request was already submitted zurückkommen. Behandle es als Duplikat, nicht als Credit-Problem.

Kurs und Gleichlaufbahn

Code	Status	Bedeutung
`RATE_LIMITED`	429	Zu viele Anfragen. Warte `retryAfter` (oder `details.retryAfter`) Sekunden.
`CONCURRENT_LIMIT`	429	Zu viele Renderings laufen gleichzeitig. Warte, bis einer fertig ist.

Dienst

Code	Status	Bedeutung
`USAGE_CHECK_UNAVAILABLE`	503	Die Nutzung konnte nicht überprüft werden, daher wurde das Rendering pausiert. Es wurde nichts berechnet.
`DB_UNAVAILABLE`	503	Ein Dienst ist kurzzeitig nicht verfügbar.
`FEATURE_NOT_AVAILABLE`	503	Rendering ist derzeit nicht verfügbar.
`GLOBAL_KILL_SWITCH`	503	Das Rendern ist für alle pausiert.
`FEATURE_KILL_SWITCH`	503	Diese Funktion ist pausiert.
`USER_KILL_SWITCH`	503	Dieses Konto ist vorübergehend eingeschränkt. Kontaktieren Sie den Support.

Webhooks

Code	Status	Bedeutung
`UNKNOWN_EVENT`	400	Kein Event, das du abonnieren kannst. Die Antwort listet die gültigen auf.
`URL_NOT_DELIVERABLE`	400	Die URL ist keine öffentliche http(s)-Adresse.
`HOOK_LIMIT`	409	Das Konto hat bereits die maximale Anzahl an Webhooks.

Versuch es sicher erneut

Versuchen Sie es erneut 429, 500, 502 und 503 mit Backoff. Versuchen Sie es nicht mit anderen 4xx unverändert.
Schicken Sie immer einen Idempotency-Key auf POST /v1/render.
Keine Antwort überhaupt (ein Timeout oder eine unterbrochene Verbindung): Versuchen Sie es mit demselben Schlüssel erneut. Wenn die erste Anfrage tatsächlich ein Rendering startet, wird der Wiederversuch abgelehnt, anstatt einen zweiten zu starten.
Eine Fehlerantwort: Für diese Anfrage wurde kein Rendering gestartet. Beheben Sie die Ursache und versuchen Sie es dann erneut mit einem neuen Schlüssel, denn eine Anfrage, die teilweise fehlgeschlagen ist, könnte ihren Schlüssel bereits verwendet haben. Render-Credits werden zurückerstattet. Die einzige Gebühr, die nicht erstattet wird, ist Kurzplanung, bei der das geplante Render dann abgelehnt wird (siehe Videos erstellen).
Wenn ein Render angenommen wurde (202) und später scheitert, wird der status des Auftrags failed und error erklärt warum. Credits für Arbeiten, die nicht erledigt wurden, werden erstattet.