Errores

Todos los errores de los endpoints de Video API usan la misma forma JSON:

{
  "error": {
    "code": "...",
    "message": "..."
  }
}

El estado HTTP indica la clase del problema; error.code es un string estable que puedes usar para bifurcar en el código. Siempre compara con error.code en lugar de parsear error.message.

Códigos de error

references_conflict y too_many_references son errores de validación del cuerpo de la solicitud; ver Crear video para los límites exactos. cancel_not_supported y cancel_failed se describen en Cancelar video. not_found se devuelve tanto para un trabajo desconocido como para un trabajo propiedad de otra API Key; los dos casos son indistinguibles de forma intencional.

Errores de preprocesamiento de real_person

Cuando el preprocesamiento de imágenes con real_person: true falla por la imagen suministrada, la API devuelve HTTP 400 con error.code: "invalid_request". El final de error.message incluye uno de estos motivos estables e identifica la referencia que falló, por ejemplo input_references[0]:

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

En la lógica de la aplicación, sigue bifurcando por error.code. Usa el motivo y la ubicación de la referencia para corregir la entrada o diagnosticar el problema.

402 Créditos insuficientes

insufficient_credits se devuelve solo cuando creas un trabajo (POST /v1/videos). Cuando la preautorización está habilitada, ofox estima el costo a partir de la resolución y duración solicitadas antes de aceptar el trabajo. Si la estimación supera tu saldo, la solicitud se rechaza de inmediato: no se crea ningún registro de trabajo y no se cobra nada.

{ "error": { "code": "insufficient_credits", "message": "..." } }

429 Límite de tasa

rate_limited cubre tanto el límite de consulta por key en GET /v1/videos/{id} como los límites de tasa upstream. Cuando alcanzas el límite de consulta, la respuesta incluye un header Retry-After:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
 
{ "error": { "code": "rate_limited", "message": "..." } }

Respeta el header Retry-After y espera antes de volver a intentar. Si estás consultando con frecuencia, cambia a notificaciones webhook para que ofox te envíe el estado terminal; esto evita por completo el límite de consulta. La creación de trabajos (POST) y la cancelación (DELETE) no se ven afectadas por el límite de consulta.