Saltar al contenido principal

Formato de Respuesta de Error

Cuando una tarea falla (status: "failed"), la respuesta incluye un objeto error:

Resumen de Codigos de Error

Errores del Cliente (Corregibles por el Usuario)


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:
Desencadenantes comunes:
Como evitarlo:
  • Evite subir fotos reales de personas — use estilos de ilustracion o dibujos animados
  • Elimine logotipos de marcas, marcas registradas y personajes de PI con derechos de autor
  • Evite temas de adultos, violencia o autolesion
  • Use descripciones genericas de personajes (por ejemplo, “a person”) en lugar de referirse a celebridades especificas

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.
Causas comunes:
  • 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.)
Como solucionarlo:
  • Ajuste su prompt para que sea mas claro y especifico
  • Use diferentes imagenes de referencia — evite imagenes con marcas de agua o logotipos
  • Simplifique la solicitud (menor resolucion o complejidad)
  • Simplemente reintente — algunos casos tienen exito al reintentar

invalid_parameters

Parametros Invalidos

Los parametros de la solicitud no cumplen con los requisitos del modelo.
Subtipos comunes:
Como solucionarlo:
  • Consulte la documentacion de la API especifica del modelo para los requisitos de parametros
  • Formatos de imagen soportados: JPG, PNG, WebP, GIF (HEIC, AVIF, TIFF no son soportados)
  • Limites de tamano de imagen: tipicamente < 10MB, algunos modelos < 30MB
  • Acorte su prompt o divida prompts largos en descripciones esenciales

image_processing_error

Error de Procesamiento de Imagen

El sistema no pudo procesar la imagen de entrada.
Causas comunes:
  • 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
Como solucionarlo:
  • Asegurese de que la URL de la imagen sea accesible publicamente sin autenticacion ni restricciones de region
  • Use formatos estandar: JPG, PNG, WebP
  • Intente usar la API de carga de archivos en lugar de URLs
  • Verifique que la imagen se abra correctamente en un navegador

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.
Ejemplo:
  • aspect_ratio=1280x720 (16:9) requiere una imagen horizontal de 1280x720
  • aspect_ratio=720x1280 (9:16) requiere una imagen vertical de 720x1280
Como solucionarlo: Redimensione su imagen para que coincida con el parametro aspect_ratio solicitado, o cambie el aspect_ratio para que coincida con su imagen.

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.
Causas comunes:
  • Servicio del modelo upstream temporalmente no disponible
  • Sobrecarga del servidor / alto trafico
  • Mantenimiento en curso
  • Conexion de red interrumpida
Como solucionarlo:
  • Espere 30-60 segundos y reintente — el sistema generalmente se recupera automaticamente
  • Si persiste, contacte al soporte tecnico
  • No necesita modificar su solicitud — reintente la misma solicitud

generation_timeout

Tiempo de Generacion Agotado

La tarea no se completo dentro del tiempo permitido.
Causas comunes:
  • Alta carga del sistema causando retrasos en la cola
  • Alta complejidad de la tarea (alta resolucion, video largo, etc.)
  • Respuesta lenta del servicio upstream
Como solucionarlo:
  • Reintente mas tarde, preferiblemente durante horas de menor demanda
  • Reduzca la complejidad de la tarea: menor resolucion, menor duracion del video
  • Simplifique las descripciones del prompt

quota_exceeded

Cuota / Limite de Frecuencia Excedida

Se han excedido los limites de frecuencia de solicitud o concurrencia.
Causas comunes:
  • Demasiadas solicitudes enviadas en un corto periodo (limitacion de frecuencia)
  • Multiples tareas procesandose simultaneamente (limite de concurrencia)
  • Cuota de la cuenta agotada
Como solucionarlo:
  • Reduzca la frecuencia de solicitudes — intervalo recomendado de 1-2 segundos entre solicitudes
  • Espere a que las tareas en curso se completen antes de enviar nuevas
  • Si la cuota esta agotada, visite la pagina de facturacion para recargar

resource_exhausted

Recursos Agotados

Los recursos de computo del servicio upstream estan temporalmente agotados. Generalmente ocurre durante periodos de uso pico del modelo.
Como solucionarlo:
  • Espere 1-5 minutos para la recuperacion automatica
  • El sistema cambia automaticamente entre multiples rutas — reintentar mas tarde generalmente tiene exito

resource_not_found

Recurso No Encontrado

El ID de tarea solicitado no existe o ha expirado.
Como solucionarlo:
  • Verifique que el ID de tarea este escrito correctamente
  • Los resultados de tareas tienen un periodo de expiracion — las tareas expiradas no se pueden consultar
  • Si el ID es correcto, reintente despues de una breve espera

request_cancelled

Solicitud Cancelada

La tarea fue cancelada o interrumpida durante el procesamiento.
Si no cancelo intencionalmente, simplemente reenvie la misma solicitud.

service_unavailable

Servicio No Disponible

Ocurrio un problema interno de autenticacion o conexion. Este error ha sido registrado automaticamente y tipicamente se resolvera rapidamente.
Como solucionarlo:
  • Espere unos minutos y reintente
  • Si persiste, contacte al soporte tecnico con su ID de tarea

unknown_error

Error Desconocido

Un error no clasificado. El sistema no pudo identificar el tipo de error especifico.
Como solucionarlo:
  • Reintente despues de una breve espera
  • Si el problema persiste, contacte al soporte tecnico con el ID de tarea completo

Mejores Practicas

Ejemplo de Manejo de Errores

Reintentable vs No Reintentable

Corregir Solicitud Antes de Reintentar

  • content_policy_violation — Modificar contenido
  • invalid_parameters — Corregir parametros
  • image_processing_error — Usar otra imagen
  • image_dimension_mismatch — Redimensionar imagen

Seguro para Reintentar Directamente

  • generation_failed_no_content — Intentar con otro prompt
  • service_error — Esperar, luego reintentar
  • generation_timeout — Esperar, luego reintentar
  • resource_exhausted — Se recupera automaticamente
  • quota_exceeded — Reducir frecuencia, luego reintentar