Erreurs

L’API utilise les codes d’état HTTP habituels : 2xx indique une réussite, 4xx que la requête doit être modifiée et 5xx qu’une erreur s’est produite de notre côté ou en amont. Toutes les réponses d’erreur ont la même structure JSON, ce qui permet de les traiter au même endroit.

Format des erreurs#

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

• code — une chaîne stable et lisible par machine. Utilisez-la dans vos conditions, pas le message.
• message — une explication lisible par un humain, que vous pouvez enregistrer dans les logs. Sa formulation peut évoluer.
• param — présent lorsqu’un champ précis de la requête est à l’origine de l’erreur.

Codes d’erreur#

Erreurs au cours d’une génération#

Une erreur HTTP signifie que la requête elle-même a été rejetée et qu’aucun montant n’a été débité. Le cas d’une génération acceptée qui échoue ensuite est différent : l’appel API a réussi (même si POST /run renvoie 202 lorsqu’une tâche échoue immédiatement), puis status de la génération passe à failed avec un objet error. Le montant réservé est automatiquement remboursé. Le même objet figure dans GET /generations, la charge utile notification webhook et les résultats des outils MCP.

{
  "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": "Votre requête n’a pas passé le contrôle de sécurité du contenu. Modifiez votre prompt et réessayez."
  }
}

code désigne la catégorie générale (les quatre valeurs documentées depuis le lancement). reason précise la raison : utilisez-le dans vos conditions et affichez message et hint aux utilisateurs. retryable indique si un nouvel envoi de la même requête peut réussir ; param nomme le champ à modifier si nous pouvons l’identifier, et detail contient la formulation du fournisseur du modèle.

Les échecs dus à votre requête — content_blocked, un fichier refusé dans invalid_input, input_unreachable — ne sont pas réessayés auprès d’autres fournisseurs, car ils seraient de nouveau rejetés. Les pannes et erreurs des fournisseurs sont d’abord réessayées sur toutes les routes disponibles, au même prix. Voir Échecs et remboursements.

Lorsqu’un fournisseur indique qu’il ne peut pas télécharger l’un de vos fichiers d’entrée, nous essayons généralement de le télécharger nous-mêmes. Si nous y parvenons, la tâche est relancée avec une copie hébergée chez nous — au même prix, sans rien changer de votre côté ; la génération affiche toujours les URL que vous avez envoyées, et la copie est supprimée avec la génération conformément à sa retention. Ainsi, input_unreachable signifie le plus souvent que le fichier n’a pas pu être téléchargé : il nécessite une connexion, son lien signé a expiré, ne pointe pas directement vers le fichier ou son hébergeur a refusé la requête. Nous copions les images jusqu’à 30 MB, les vidéos jusqu’à 200 MB et l’audio jusqu’à 50 MB ; un fichier plus volumineux ou illisible échoue avec le statut invalid_input.

Réessayer sans risque#

Réessayez 429, 500, 502 et 503 avec un délai exponentiel et une part d’aléatoire. Ne réessayez pas les autres erreurs 4xx sans modifier la requête : elle échouerait de la même façon.

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()

Exemples de validation#

Les messages de validation indiquent le champ et les valeurs autorisées ; vous pouvez les afficher tels quels aux développeurs :

[
  {
    "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."
    }
  }
]

Vous pouvez aussi calculer le prix d’une requête sans lancer de génération : POST /api/v1/quote/{endpoint} valide les champs qui déterminent le prix et renvoie le coût. Voir Référence de l’API.