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.

Erreurs de prétraitement `real_person`

Lorsque le prétraitement d’image avec real_person: true échoue à cause de l’image fournie, l’API renvoie HTTP 400 avec error.code: "invalid_request". La fin de error.message contient l’un des motifs stables suivants et identifie la référence en erreur, par exemple input_references[0] :

Motif	Correction
`bad_data_uri`	L’URI `data:` est mal formée ou sa charge base64 est invalide
`download_failed`	L’image n’a pas pu être téléchargée en raison d’une connexion, d’un délai d’attente ou d’un contrôle d’accès
`unreachable`	L’URL de l’image a renvoyé un statut HTTP d’échec
`not_image`	Le contenu téléchargé n’est pas une image prise en charge et décodable
`too_large`	L’image dépasse la limite de taille, de pixels ou de traitement par requête


{
  "error": {
    "code": "invalid_request",
    "message": "real_person image processing failed — input_references[0]: ... (not_image)"
  }
}

Dans la logique applicative, continuez à brancher sur error.code. Utilisez le motif et l’emplacement de la référence pour corriger l’entrée ou diagnostiquer le problème.

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.