Errores

Cuando una petición falla, el código HTTP dice de qué tipo es el fallo, y el cuerpo tiene siempre la misma forma:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid upload.",
    "details": ["size: the file size in bytes is required."]
  }
}

• code es estable: decide con él.
• message es texto en inglés para personas (para tus logs). Puede cambiar; no compares con él.
• details lista cada problema, como ruta: mensaje, en los errores de validación; en los demás va vacío.

HTTP	code	Cuándo	¿Reintentar?
400	validation_error	Campos inválidos o desconocidos. details nombra cada uno.	No: corrige la petición.
401	unauthorized	La API key falta, no es válida o está revocada.	No.
402	quota_exceeded	Tu plan no lo permite: se acabaron los minutos del mes, o el archivo supera el tamaño máximo del plan.	Tras mejorar el plan, o el mes siguiente.
402	insufficient_balance	Se agotó tu saldo: el saldo incluido del mes y tu saldo prepagado. Los jobs que ya están en marcha terminan.	Tras recargar, o cuando se renueve el saldo del mes.
403	forbidden	Credenciales válidas que no pueden hacer esto, como gestionar API keys o endpoints de webhooks con una API key (eso se hace en el panel).	No.
403	module_not_in_plan	Tu plan no incluye el módulo al que pertenece la ruta (transcoding…). Los módulos de tu organización están en GET /v1/organization, como modules.	Cuando el módulo se añada a tu plan.
403	organization_suspended	Tu organización está suspendida, así que no se puede hacer nada en su nombre. Tu panel indica a quién escribir.	Después de que se restablezca.
404	not_found	El recurso no existe en tu organización, o la ruta no existe.	No.
409	conflict	Su estado no lo permite: cancelar un job terminado, reintentar un job cuya fuente subida caducó, un Idempotency-Key reutilizado con otro cuerpo.	No.
429	—	Demasiadas peticiones. Lo envía la pasarela delante de la API, así que su cuerpo puede ser distinto.	Sí, tras una pausa.
500	internal_error	Nuestro.	Sí; avísanos si persiste.
503	service_unavailable	No disponible por un momento.	Sí, tras unos segundos.

Reintentar sin riesgo

Reintenta los 429, 500, 503 y los fallos de red con espera exponencial (1 s, 2 s, 4 s… hasta un minuto más o menos). Leer siempre se puede repetir. Para que crear un job se pueda repetir, envíalo con un Idempotency-Key: una petición repetida con la misma clave devuelve el job creado la primera vez en vez de otro.

Un job que falla después de crearse es otra cosa: tiene su propio error, explicado en Cuando un job falla.