Formato de Respuesta de Error
Cuando una tarea falla (status: "failed"), la respuesta incluye un objeto error:
| Campo | Tipo | Descripcion |
|---|---|---|
error.code | string | Identificador del codigo de error. Ver la lista completa a continuacion |
error.message | string | Descripcion del error con consejos de solucion de problemas |
Resumen de Codigos de Error
Errores del Cliente (Corregibles por el Usuario)
Errores del Cliente (Corregibles por el Usuario)
| Codigo de Error | Descripcion | Reintentable |
|---|---|---|
content_policy_violation | El contenido viola las politicas de seguridad | Corregir contenido, luego reintentar |
invalid_parameters | Parametros de solicitud invalidos | Corregir parametros, luego reintentar |
image_processing_error | Error en el procesamiento de imagen | Usar otra imagen |
image_dimension_mismatch | Las dimensiones de la imagen no coinciden con la solicitud | Redimensionar imagen, luego reintentar |
request_cancelled | La solicitud fue cancelada | Reenviar |
Errores del Servidor (Reintentar mas tarde)
Errores del Servidor (Reintentar mas tarde)
| Codigo de Error | Descripcion | Reintentable |
|---|---|---|
generation_failed_no_content | El modelo no pudo generar contenido | Intentar con otro prompt |
service_error | Error interno del servicio | Se recupera automaticamente, reintentar mas tarde |
generation_timeout | El procesamiento de la tarea expiro | Reintentar mas tarde |
resource_exhausted | Recursos upstream temporalmente agotados | Se recupera automaticamente, reintentar mas tarde |
quota_exceeded | Limite de frecuencia o cuota excedida | Reducir frecuencia, reintentar mas tarde |
service_unavailable | Servicio temporalmente no disponible | Se recupera automaticamente, reintentar mas tarde |
resource_not_found | ID de tarea invalido o expirado | Verificar ID de tarea |
unknown_error | Error no clasificado | Contactar soporte |
Detalles de Codigos de Error
content_policy_violation
Violacion de Politica de Contenido
Su solicitud fue bloqueada por los filtros de seguridad. Este es el tipo de error mas comun, que cubre los siguientes escenarios:
| Subtipo | Descripcion | Mensaje de ejemplo |
|---|---|---|
| Personas fotorrealistas | La imagen subida contiene rostros humanos reales | photorealistic people detected |
| Semejanza con celebridades | Involucra celebridades o figuras publicas | celebrity detected in image |
| Derechos de autor/Marcas | Involucra logotipos de marcas, marcas registradas o PI con derechos de autor | third-party content violation |
| Adulto/NSFW | Contiene desnudez o contenido sexualmente sugerente | nudity detected |
| Violencia/Autolesion | Contiene contenido violento, grafico o de autolesion | violence content blocked |
| Proteccion de menores | Involucra contenido sensible relacionado con menores | minor content not allowed |
| Politica general | Otras violaciones de politica de contenido | content policy violation |
generation_failed_no_content
Generacion Fallida
El modelo no pudo producir contenido para su solicitud. Aunque el formato de la solicitud era valido, el modelo no pudo generar un resultado durante el procesamiento.
- Calidad deficiente del prompt: La descripcion es demasiado vaga o contradictoria para que el modelo la entienda
- Limites de capacidad del modelo: El prompt excede las capacidades de generacion del modelo
- Problemas del servicio upstream: El servicio del modelo subyacente devolvio un resultado vacio
- Deteccion de contenido protegido: El prompt o la imagen de referencia puede involucrar eliminacion de marcas de agua o contenido protegido (logotipos, marcas registradas, etc.)
invalid_parameters
Parametros Invalidos
Los parametros de la solicitud no cumplen con los requisitos del modelo.
| Subtipo | Descripcion | Ejemplo |
|---|---|---|
| Prompt demasiado largo | El prompt excede la longitud maxima del modelo | Prompt is too long |
| Dimension de imagen | El ancho/alto o la relacion de aspecto de la imagen esta fuera de rango | image dimensions must be between 240 and 7680 |
| Archivo demasiado grande | El archivo subido excede el limite de tamano | file size exceeds 10MB |
| Formato no soportado | El formato del archivo subido no es compatible | unsupported file type |
| Duracion de video | La duracion del video esta fuera del rango soportado por el modelo | Video duration must be between 1-30 seconds |
image_processing_error
Error de Procesamiento de Imagen
El sistema no pudo procesar la imagen de entrada.
- La URL de la imagen no es accesible (requiere autenticacion, restricciones de CDN, enlace expirado)
- El formato de imagen no es compatible (por ejemplo, HEIC, AVIF)
- El archivo de imagen esta danado
- Problemas de red impidieron la descarga de la imagen
image_dimension_mismatch
Desajuste de Dimensiones de Imagen
Las dimensiones de la imagen de entrada no coinciden con las dimensiones especificadas en la solicitud. Comun en escenarios de imagen a video.
aspect_ratio=1280x720(16:9) requiere una imagen horizontal de 1280x720aspect_ratio=720x1280(9:16) requiere una imagen vertical de 720x1280
service_error
Error de Servicio
Ocurrio un problema interno en el servicio upstream. Esto suele ser temporal — el sistema cambia automaticamente a otras rutas disponibles.
- Servicio del modelo upstream temporalmente no disponible
- Sobrecarga del servidor / alto trafico
- Mantenimiento en curso
- Conexion de red interrumpida
generation_timeout
Tiempo de Generacion Agotado
La tarea no se completo dentro del tiempo permitido.
- Alta carga del sistema causando retrasos en la cola
- Alta complejidad de la tarea (alta resolucion, video largo, etc.)
- Respuesta lenta del servicio upstream
quota_exceeded
Cuota / Limite de Frecuencia Excedida
Se han excedido los limites de frecuencia de solicitud o concurrencia.
- Demasiadas solicitudes enviadas en un corto periodo (limitacion de frecuencia)
- Multiples tareas procesandose simultaneamente (limite de concurrencia)
- Cuota de la cuenta agotada
resource_exhausted
Recursos Agotados
Los recursos de computo del servicio upstream estan temporalmente agotados. Generalmente ocurre durante periodos de uso pico del modelo.
resource_not_found
Recurso No Encontrado
El ID de tarea solicitado no existe o ha expirado.
request_cancelled
Solicitud Cancelada
La tarea fue cancelada o interrumpida durante el procesamiento.
service_unavailable
Servicio No Disponible
Ocurrio un problema interno de autenticacion o conexion. Este error ha sido registrado automaticamente y tipicamente se resolvera rapidamente.
unknown_error
Error Desconocido
Un error no clasificado. El sistema no pudo identificar el tipo de error especifico.
Mejores Practicas
Ejemplo de Manejo de Errores
Reintentable vs No Reintentable
Corregir Solicitud Antes de Reintentar
content_policy_violation— Modificar contenidoinvalid_parameters— Corregir parametrosimage_processing_error— Usar otra imagenimage_dimension_mismatch— Redimensionar imagen
Seguro para Reintentar Directamente
generation_failed_no_content— Intentar con otro promptservice_error— Esperar, luego reintentargeneration_timeout— Esperar, luego reintentarresource_exhausted— Se recupera automaticamentequota_exceeded— Reducir frecuencia, luego reintentar