Fehler
Jeder Fehler der Video API-Endpunkte verwendet dieselbe JSON-Form:
{
"error": {
"code": "...",
"message": "..."
}
}Der HTTP-Status gibt die Problemklasse an; error.code ist ein stabiler String, auf den Sie im Code verzweigen können. Stimmen Sie immer auf error.code ab, statt error.message zu parsen.
Fehlercodes
| HTTP | Code | Bedeutung |
|---|---|---|
| 400 | invalid_request | Ein Pflichtparameter fehlt oder ein Wert ist ungültig |
| 400 | invalid_callback_url | callback_url ist nicht HTTPS oder zeigt auf ein privates Netzwerk (durch SSRF-Prüfungen blockiert) |
| 400 | references_conflict | frame_images und input_references wurden in derselben Anfrage gesendet (gegenseitig ausgeschlossen) |
| 400 | too_many_references | input_references überschreitet die Limits (Bilder > 9 / Audio > 3 / Video > 1) |
| 400 | cancel_not_supported | Der Upstream-Anbieter kann diesen Job nicht unterbrechen |
| 400 | cancel_failed | Der Job befindet sich bereits in einem terminalen Zustand und kann nicht abgebrochen werden |
| 401 | unauthorized / invalid_api_key | Authentifizierung fehlgeschlagen |
| 401 | upstream_auth_failed | Authentifizierung beim Upstream-Anbieter fehlgeschlagen |
| 402 | insufficient_credits | Nicht genug Guthaben, um den Job anzunehmen |
| 404 | not_found | Der Job existiert nicht oder Sie haben keinen Zugriff darauf |
| 404 | model_not_found | Das angefragte Modell existiert nicht |
| 429 | rate_limited | Zu viele Anfragen (Polling-Ratenbegrenzung oder Upstream-Ratenlimit) |
| 502 | upstream_error / route_error | Fehler beim Upstream-Anbieter / Routing-Fehler |
| 500 | internal_error | Unerwarteter interner Fehler |
references_conflict und too_many_references sind Validierungsfehler im Request Body — die genauen Limits finden Sie unter Video erstellen. cancel_not_supported und cancel_failed werden unter Video abbrechen beschrieben. not_found wird sowohl für einen unbekannten Job als auch für einen Job zurückgegeben, der einem anderen API Key gehört; die beiden Fälle sind absichtlich nicht unterscheidbar.
402 Insufficient credits
insufficient_credits wird nur beim Erstellen eines Jobs (POST /v1/videos) zurückgegeben. Wenn die Vorabautorisierung aktiviert ist, schätzt ofox die Kosten anhand der angefragten Auflösung und Dauer, bevor der Job angenommen wird. Wenn diese Schätzung Ihr Guthaben überschreitet, wird die Anfrage sofort abgelehnt — es wird kein Job-Datensatz erstellt und nichts berechnet.
{ "error": { "code": "insufficient_credits", "message": "..." } }insufficient_credits ist der einzige 402-Code, den die Video API zurückgibt. Behandeln Sie diesen einen Code, laden Sie Ihr Guthaben auf und versuchen Sie es erneut.
429 Rate limiting
rate_limited deckt sowohl das Pro-Key-Polling-Limit für GET /v1/videos/{id} als auch Upstream-Ratenlimits ab. Wenn Sie das Polling-Limit erreichen, enthält die Antwort einen Retry-After-Header:
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
{ "error": { "code": "rate_limited", "message": "..." } }Beachten Sie den Retry-After-Header und warten Sie vor einem erneuten Versuch. Wenn Sie häufig per Polling abfragen, wechseln Sie zu Webhook-Benachrichtigungen, damit ofox den terminalen Zustand stattdessen an Sie pusht — dadurch umgehen Sie das Polling-Limit vollständig. Joberstellung (POST) und Abbruch (DELETE) sind vom Polling-Limit nicht betroffen.