Errores

En esta guía, hablaremos sobre lo que sucede cuando algo sale mal mientras trabajas con la Meshy API.

Errores de solicitud

Estos errores se devuelven inmediatamente cuando se rechaza tu solicitud de API. Consulta el código de estado HTTP y el campo message para entender qué salió mal.

{
  "message": "Invalid model file extension: .3dm"
}

Errores de tarea

Estos errores ocurren después de que una tarea se ha creado y está en procesamiento. Consulta el objeto task_error en la respuesta de la tarea para ver los detalles del error.

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

Tipos de error

El campo type indica la categoría general del fallo. Úsalo para decidir tu estrategia de reintento.

Códigos de error

Cuando el campo code está presente, identifica un problema específico y accionable. A continuación se muestra la referencia completa de cada código de error.

image_too_complex

Este error ocurre cuando la imagen de entrada o el prompt describe un sujeto que es demasiado complejo geométricamente para que el modelo de generación 3D lo procese.

Los ejemplos comunes incluyen:

• Montones densos de objetos pequeños (p. ej., una caja llena de fruta, una pila de libros)
• Patrones repetitivos intrincados (p. ej., estructuras reticulares, andamios, mallas de alambre)
• Estructuras de edificios complejas (p. ej., edificios de varios pisos con muchas ventanas y balcones)
• Múltiples objetos distintos en una imagen en lugar de un solo sujeto

Ejemplos de entradas que probablemente sean demasiado complejas:

Resolución:

1. Usa un solo objeto por imagen. El modelo funciona mejor con un sujeto claro. No incluyas varios objetos separados en la misma imagen o prompt.
2. Simplifica tu sujeto. Reduce el nivel de detalle. Por ejemplo, un jarrón simple en lugar de un jarrón lleno de docenas de flores.
3. Evita prompts a nivel de escena. Es probable que edificios completos, manzanas urbanas, interiores llenos de muebles o paisajes superen la capacidad del modelo. En su lugar, céntrate en un solo objeto.
4. Evita estructuras repetitivas densas. Sujetos como andamios, mallas de alambre, patrones reticulares o montones de muchos elementos pequeños son desencadenantes comunes.

model_missing_uv

Este error ocurre cuando subes un modelo para aplicarle texturas con enable_original_uv establecido en true, pero el modelo no tiene coordenadas UV. Las coordenadas UV definen cómo una textura 2D se ajusta a la superficie 3D de tu modelo.

Resolución:

La corrección adecuada depende de por qué estableciste enable_original_uv en true:

• Si necesitas conservar la distribución UV original de tu modelo (por ejemplo, colocación personalizada de costuras para un mapeo de textura preciso): tu modelo debe tener coordenadas UV válidas. Verifica que existan UV en el editor de UV de tu software 3D antes de subirlo. Ten en cuenta que los archivos STL no pueden almacenar datos UV, así que usa GLB, FBX u OBJ en su lugar.
• Si no necesitas control UV específico (o no estás seguro): omite enable_original_uv o establécelo en false. El sistema generará automáticamente una distribución UV para tu modelo. Las UV generadas automáticamente están optimizadas para la cobertura, pero no tendrás control sobre dónde se colocan las costuras de la textura.

model_insufficient_uv

Este error se produce cuando un modelo tiene coordenadas UV, pero la cobertura UV es demasiado pequeña para un texturizado de calidad. Esto suele ocurrir con modelos exportados desde herramientas 3D que generan UV de marcador de posición o colapsadas sin un desenvolvimiento adecuado.

Resolución:

• Si necesitas conservar tu distribución UV original: vuelve a desenvolver las UV del modelo en tu software 3D. Asegúrate de que las islas UV estén distribuidas correctamente por el espacio UV en lugar de estar colapsadas en un área pequeña.
• Si no necesitas un control UV específico: omite enable_original_uv o establécelo en false. El sistema generará automáticamente una nueva distribución UV. La contrapartida es que perderás la colocación original de las costuras, pero las UV generadas automáticamente tendrán una cobertura adecuada para el texturizado.

invalid_input

Este es el código de error de respaldo cuando la entrada no supera la validación, pero no se aplica ningún código más específico. El campo message contiene el motivo específico del fallo.

Las causas comunes incluyen:

• Archivos de modelo vacíos o dañados
• Variaciones de formato de archivo no compatibles (p. ej., archivos FBX ASCII, GLB comprimido con meshopt)
• No se encontraron objetos 3D válidos en el modelo subido (p. ej., el archivo contiene solo esqueletos (armature), cámaras o luces)
• Contenido que no supera los filtros de seguridad

Resolución: Consulta el campo message para obtener detalles sobre lo que salió mal. Verifica que tus archivos de entrada y parámetros coincidan con los requisitos del endpoint.

moderation_blocked

Este error ocurre cuando tu prompt o las imágenes de referencia son rechazados por los filtros de seguridad de IA. El filtro evalúa juntos tanto el prompt de texto como cualquier imagen de referencia.

Solución:

• Reformula tu prompt de texto para eliminar descripciones sugestivas o sensibles.
• Ajusta las imágenes de referencia si muestran contenido que pueda activar los filtros de seguridad.

timeout

Este error significa que el tiempo de procesamiento de tu tarea superó el límite permitido. Esto puede ocurrir debido a una alta carga del sistema o porque la entrada es demasiado compleja para procesarla dentro del límite de tiempo.

Resolución:

1. Vuelve a intentar la solicitud. Los timeout suelen ser transitorios y un nuevo intento puede tener éxito.
2. Simplifica tu entrada. Si los reintentos siguen fallando, tu entrada puede ser demasiado compleja. Intenta reducir el nivel de detalle en tu imagen o prompt. Consulta image_too_complex para obtener orientación sobre qué tipos de entradas son más difíciles de procesar.

format_conversion_failed

Este error ocurre cuando el modelo 3D generado no pudo convertirse al formato de salida solicitado. El modelo se generó correctamente, pero falló el paso de conversión.

Resolución:

1. Vuelve a intentar la solicitud.
2. Prueba un formato de salida diferente. Si un formato específico sigue fallando, cambia a otro formato que se adapte a tus necesidades.

Mejores prácticas

1. Implementa lógica de reintento. Para errores de timeout y service_unavailable, implementa lógica de reintento con backoff exponencial.
2. Registra los IDs de tarea. Registra siempre el ID de la tarea para fines de depuración. Inclúyelo al contactar con soporte.
3. Valida las entradas. Asegúrate de que tus imágenes y modelos de entrada cumplan los requisitos de formato antes del envío.