Errores

La API usa los códigos de estado HTTP habituales: 2xx indica éxito, 4xx que debes modificar la solicitud y 5xx que se produjo un error en nuestro sistema o en un servicio externo. Todas las respuestas de error tienen el mismo formato JSON, así que puedes gestionarlas en un solo lugar.

Formato de error#

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

• code: una cadena estable y legible por máquinas. Usa este valor para tomar decisiones en el código, no el mensaje.
• message: una explicación legible por personas y segura para incluir en los registros. La redacción puede cambiar.
• param: aparece cuando un campo específico de la solicitud causó el error.

Códigos de error#

Errores durante una generación#

Un error HTTP significa que se rechazó la solicitud y no se cobró nada. Es distinto de una generación aceptada que falla más tarde: la llamada a la API se realizó correctamente (incluso POST /run devuelve 202 si una tarea falla de inmediato) y el status de la generación pasa a ser failed, con un objeto error. El importe reservado se reembolsa automáticamente. El mismo objeto aparece en GET /generations, en la carga webhook y en los resultados de las herramientas 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": "Tu solicitud no superó la revisión de seguridad del contenido. Ajusta el prompt y vuelve a intentarlo."
  }
}

code es la categoría general (los cuatro valores documentados desde el lanzamiento). reason explica exactamente el motivo; úsalo en el código y muestra message y hint a tus usuarios. retryable indica si se puede volver a enviar la misma solicitud; param especifica qué campo cambiar, si se puede determinar, y detail contiene el texto del proveedor del modelo.

Los fallos causados por tu solicitud —content_blocked, un archivo rechazado en invalid_input o input_unreachable— no se reintentan en otros proveedores, porque volverían a rechazarse. Primero se reintentan los cortes del servicio y los errores del proveedor en todas las rutas compatibles, al mismo precio. Consulta Fallos y reembolsos.

Cuando un proveedor indica que no puede descargar uno de tus archivos de entrada, normalmente intentamos descargarlo nosotros. Si podemos, volvemos a intentar el trabajo con una copia alojada por nosotros, al mismo precio y sin que tengas que cambiar nada; la generación sigue mostrando las URL que enviaste y la copia se elimina junto con la generación según su retención. Por eso, input_unreachable suele significar que no se pudo descargar el archivo en absoluto: requiere iniciar sesión, el enlace firmado ha caducado, no apunta directamente al archivo o el servidor de origen rechazó la solicitud. Copiamos imágenes de hasta 30 MB, videos de hasta 200 MB y audio de hasta 50 MB; los archivos más grandes o ilegibles fallan con invalid_input.

Reintentar de forma segura#

Reintenta los errores 429, 500, 502 y 503 con retroceso exponencial y fluctuación aleatoria. No reintentes sin cambios otros errores 4xx; volverán a fallar por el mismo motivo.

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

Ejemplos de validación#

Los mensajes de validación indican el campo y los valores permitidos, así que puedes mostrárselos directamente a los desarrolladores:

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

También puedes consultar el precio sin ejecutar la solicitud: POST /api/v1/quote/{endpoint} valida los campos que afectan al precio y devuelve el coste. Consulta referencia de la API.