Erreurs
Chaque erreur provenant des endpoints Video API utilise la même forme JSON :
{
"error": {
"code": "...",
"message": "..."
}
}Le statut HTTP indique la classe du problème ; error.code est une chaîne stable sur laquelle vous pouvez brancher votre code. Faites toujours la correspondance sur error.code plutôt que de parser error.message.
Codes d’erreur
| HTTP | Code | Signification |
|---|---|---|
| 400 | invalid_request | Un paramètre obligatoire est manquant ou une valeur est invalide |
| 400 | invalid_callback_url | callback_url n’est pas en HTTPS ou pointe vers un réseau privé (bloqué par les contrôles SSRF) |
| 400 | references_conflict | frame_images et input_references ont été envoyés dans la même requête (mutuellement exclusifs) |
| 400 | too_many_references | input_references dépasse les limites (images > 9 / audio > 3 / vidéo > 1) |
| 400 | cancel_not_supported | Le fournisseur en amont ne peut pas interrompre cette tâche |
| 400 | cancel_failed | La tâche est déjà dans un état terminal et ne peut pas être annulée |
| 401 | unauthorized / invalid_api_key | Échec de l’authentification |
| 401 | upstream_auth_failed | Échec de l’authentification auprès du fournisseur en amont |
| 402 | insufficient_credits | Solde insuffisant pour accepter la tâche |
| 404 | not_found | La tâche n’existe pas, ou vous n’y avez pas accès |
| 404 | model_not_found | Le modèle demandé n’existe pas |
| 429 | rate_limited | Trop de requêtes (limite de débit de polling ou limite de débit en amont) |
| 502 | upstream_error / route_error | Erreur du fournisseur en amont / échec de routage |
| 500 | internal_error | Erreur interne inattendue |
references_conflict et too_many_references sont des erreurs de validation du corps de requête — voir Créer une vidéo pour les limites exactes. cancel_not_supported et cancel_failed sont décrits dans Annuler une vidéo. not_found est renvoyé à la fois pour une tâche inconnue et une tâche détenue par une autre clé API ; les deux cas sont volontairement indiscernables.
402 Crédits insuffisants
insufficient_credits est renvoyé uniquement lorsque vous créez une tâche (POST /v1/videos). Lorsque la préautorisation est activée, ofox estime le coût à partir de la résolution et de la durée demandées avant d’accepter la tâche. Si cette estimation dépasse votre solde, la requête est rejetée immédiatement — aucun enregistrement de tâche n’est créé et rien n’est facturé.
{ "error": { "code": "insufficient_credits", "message": "..." } }insufficient_credits est le seul code 402 renvoyé par la Video API. Gérez ce code unique, rechargez votre solde, puis réessayez.
429 Limite de débit
rate_limited couvre à la fois la limite de polling par clé sur GET /v1/videos/{id} et les limites de débit en amont. Lorsque vous atteignez la limite de polling, la réponse porte un Header Retry-After :
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
{ "error": { "code": "rate_limited", "message": "..." } }Respectez le Header Retry-After et attendez avant de réessayer. Si vous interrogez fréquemment, passez aux notifications webhook afin qu’ofox vous pousse l’état terminal à la place — cela évite entièrement la limite de polling. La création de tâche (POST) et l’annulation (DELETE) ne sont pas affectées par la limite de polling.