Errores y cuotas

Estructura de los errores, códigos habituales y comportamiento de la generación con créditos gratuitos.

Formato de error

Todos los errores se devuelven en JSON con la misma estructura:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Required 10 credits, available 4, missing 6. Choose lower-cost settings to continue."
  }
}

code es estable y se puede usar para decidir cómo actuar en el código. message es una explicación legible y puede cambiar.

Códigos de error

HTTP	Código	Cuándo aparece	Qué hacer
`400`	`INVALID_INPUT`	El cuerpo no pasa la validación: falta el prompt, hay un valor no válido o se incumple una regla, como activar audio sin pro.	Corrige la petición; el mensaje indica el campo problemático.
`404`	`JOB_NOT_FOUND`	El ID no existe o la tarea no pertenece a tu clave o sesión de navegador.	Revisa el ID guardado al crear la tarea.
`402`	`INSUFFICIENT_CREDITS`	El saldo de créditos gratuitos y otros créditos no cubre el presupuesto del servidor.	Reclama los créditos gratuitos que te correspondan o elige ajustes de menor coste.
`403`	`CHALLENGE_REQUIRED`	El sistema de riesgo de generación detectó señales independientes de alto riesgo.	Completa la comprobación solicitada por el servidor y reintenta con la misma clave de idempotencia.
`429`	`GENERATION_COOLDOWN`	Una frecuencia alta y señales independientes de riesgo elevado activaron una pausa específica del modelo.	Espera a que termine; repetir peticiones no prolonga la pausa.
`502`	`CREATE_JOB_FAILED`	El sistema de generación rechazó la tarea o no pudo aceptarla.	Es un fallo transitorio: reintenta con espera exponencial.
`500`	`UNKNOWN_ERROR`	Ocurrió algo inesperado en nuestro servicio.	Reintenta una vez; si persiste, contáctanos.

Los fallos posteriores a la aceptación de una tarea no usan esta estructura: la tarea pasa a status: "failed" y el motivo aparece en errorMessage, como se explica en el ciclo de vida de las tareas.

Créditos gratuitos

Los invitados y usuarios que cumplan los requisitos reclaman los créditos gratuitos expresamente.
Los créditos gratuitos vencen a la siguiente medianoche UTC y se consumen antes que los demás.
El servidor calcula el coste según el modelo, la duración, la resolución, el audio y las opciones compatibles de video de referencia.
Si una tarea aceptada falla o se cancela, los créditos vuelven a su origen; los reembolsos de créditos gratuitos nunca se convierten en créditos de pago.

Un patrón de integración sencillo:

const res = await fetch(`${BASE}/api/ai-video/jobs`, { method: 'POST', headers, body });

if (res.status === 402) {
  const { error } = await res.json();
  if (error.code === 'INSUFFICIENT_CREDITS') {
    // retain the draft and ask the user to claim or lower the quoted cost
  }
}

¿Necesitas más que el nivel gratuito? Contáctanos y te ayudaremos a ajustar el volumen.

Formato de error

Todos los errores se devuelven en JSON con la misma estructura:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Required 10 credits, available 4, missing 6. Choose lower-cost settings to continue."
  }
}

code es estable y se puede usar para decidir cómo actuar en el código. message es una explicación legible y puede cambiar.

Códigos de error

HTTP	Código	Cuándo aparece	Qué hacer
`400`	`INVALID_INPUT`	El cuerpo no pasa la validación: falta el prompt, hay un valor no válido o se incumple una regla, como activar audio sin pro.	Corrige la petición; el mensaje indica el campo problemático.
`404`	`JOB_NOT_FOUND`	El ID no existe o la tarea no pertenece a tu clave o sesión de navegador.	Revisa el ID guardado al crear la tarea.
`402`	`INSUFFICIENT_CREDITS`	El saldo de créditos gratuitos y otros créditos no cubre el presupuesto del servidor.	Reclama los créditos gratuitos que te correspondan o elige ajustes de menor coste.
`403`	`CHALLENGE_REQUIRED`	El sistema de riesgo de generación detectó señales independientes de alto riesgo.	Completa la comprobación solicitada por el servidor y reintenta con la misma clave de idempotencia.
`429`	`GENERATION_COOLDOWN`	Una frecuencia alta y señales independientes de riesgo elevado activaron una pausa específica del modelo.	Espera a que termine; repetir peticiones no prolonga la pausa.
`502`	`CREATE_JOB_FAILED`	El sistema de generación rechazó la tarea o no pudo aceptarla.	Es un fallo transitorio: reintenta con espera exponencial.
`500`	`UNKNOWN_ERROR`	Ocurrió algo inesperado en nuestro servicio.	Reintenta una vez; si persiste, contáctanos.

Créditos gratuitos

Los invitados y usuarios que cumplan los requisitos reclaman los créditos gratuitos expresamente.
Los créditos gratuitos vencen a la siguiente medianoche UTC y se consumen antes que los demás.
El servidor calcula el coste según el modelo, la duración, la resolución, el audio y las opciones compatibles de video de referencia.
Si una tarea aceptada falla o se cancela, los créditos vuelven a su origen; los reembolsos de créditos gratuitos nunca se convierten en créditos de pago.

Un patrón de integración sencillo:

const res = await fetch(`${BASE}/api/ai-video/jobs`, { method: 'POST', headers, body });

if (res.status === 402) {
  const { error } = await res.json();
  if (error.code === 'INSUFFICIENT_CREDITS') {
    // retain the draft and ask the user to claim or lower the quoted cost
  }
}

¿Necesitas más que el nivel gratuito? Contáctanos y te ayudaremos a ajustar el volumen.

Formato de error

Códigos de error

Créditos gratuitos

Índice

Errores y cuotas

Formato de error

Códigos de error

Créditos gratuitos

Índice