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
| HTTP | Código | Significado |
|---|---|---|
| 400 | invalid_request | Falta un parámetro obligatorio o un valor es inválido |
| 400 | invalid_callback_url | callback_url no usa HTTPS o apunta a una red privada (bloqueada por verificaciones SSRF) |
| 400 | references_conflict | frame_images e input_references se enviaron en la misma solicitud (mutuamente excluyentes) |
| 400 | too_many_references | input_references excede los límites (imágenes > 9 / audio > 3 / video > 1) |
| 400 | cancel_not_supported | El proveedor upstream no puede interrumpir este trabajo |
| 400 | cancel_failed | El trabajo ya está en un estado terminal y no puede cancelarse |
| 401 | unauthorized / invalid_api_key | Autenticación fallida |
| 401 | upstream_auth_failed | Falló la autenticación del proveedor upstream |
| 402 | insufficient_credits | No hay saldo suficiente para aceptar el trabajo |
| 404 | not_found | El trabajo no existe o no tienes acceso a él |
| 404 | model_not_found | El modelo solicitado no existe |
| 429 | rate_limited | Demasiadas solicitudes (límite de tasa de consulta o límite de tasa upstream) |
| 502 | upstream_error / route_error | Error del proveedor upstream / falla de enrutamiento |
| 500 | internal_error | Error interno inesperado |
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.
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": "..." } }insufficient_credits es el único código 402 que devuelve Video API. Maneja este único código, recarga tu saldo y vuelve a intentar.
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.