Errores
Descubra por qué falló una solicitud o una tarea, y qué hacer a continuación. Una solicitud puede fallar de inmediato con un error HTTP, y una tarea puede fallar más tarde con un task_error.
Errores de solicitud
Meshy devuelve estos errores de inmediato, cuando rechaza una solicitud. Para averiguar qué salió mal, revisa el código de estado HTTP y el campo message.
Formato de respuesta
La respuesta de error tiene un campo message que describe qué salió mal:
- Name
- message
- Type
- string
- Description
Una breve descripción del error.
Códigos de estado
- Name
2xx- Description
Éxito.
- Name
200 - OK- Description
La solicitud funcionó.
- Name
202 - Accepted- Description
Meshy aceptó la solicitud, y el procesamiento aún no ha terminado. Por ejemplo, una solicitud que crea una tarea devuelve
202.
- Name
4xx- Description
Algo está mal con la solicitud o con tu cuenta. Cada estado indica qué hacer.
- Name
400 - Bad Request- Description
La solicitud no es válida, a menudo porque falta un parámetro requerido o un parámetro tiene un formato incorrecto.
- Name
401 - Unauthorized- Description
Falta la clave de API, no es válida, o no puede acceder a este endpoint. Consulta Autenticación.
- Name
402 - Payment Required- Description
La cuenta de la clave de API no tiene suficientes créditos para la solicitud. En el plan Free, la mayoría de las solicitudes que crean una tarea también devuelven
402.
- Name
403 - Forbidden- Description
No tienes permitido hacer esta solicitud, por ejemplo por una de estas razones:
- La solicitud vino de una dirección fuera de la lista blanca de IP de la clave de API.
- El filtrado de IP de tu organización bloqueó los archivos de una tarea cuando la leíste.
- El endpoint no está disponible en tu plan.
- La moderación de contenido bloqueó la entrada. Algunos endpoints devuelven
400para esto en su lugar; cada página de endpoint enumera sus códigos. - La clave de API pertenece a un miembro del equipo que ya no está activo en el equipo.
- La cuenta está suspendida.
- Name
404 - Not Found- Description
El recurso no existe. Por ejemplo, obtener una tarea con un ID que no existe devuelve
404.
- Name
409 - Conflict- Description
El recurso existe, pero su estado no permite la operación. Por ejemplo, eliminar una tarea
IN_PROGRESSdevuelve409, porque Meshy no puede reembolsar una tarea que un trabajador ya ha iniciado. La tarea sigue ejecutándose. Espera a un estado final (SUCCEEDED,FAILED, oCANCELED), y luego elimina la tarea.
- Name
422 - Unprocessable Entity- Description
La solicitud es válida, pero Meshy no puede procesar su entrada. Por ejemplo, Rigging devuelve
422cuando no puede encontrar un cuerpo humanoide en el modelo.
- Name
429 - Too Many Requests- Description
Enviaste demasiadas solicitudes, o demasiadas de tus tareas están en cola o en ejecución. Cuando la respuesta tiene un encabezado
Retry-After, espera esa cantidad de segundos, y luego reintenta. Consulta Límites de tasa.
- Name
5xx- Description
Algo salió mal del lado de Meshy. Reintenta con backoff. Si el error continúa, revisa la página de estado y contáctanos en Discord.
Example: 400 Bad Request
{
"message": "Invalid model file extension: .3dm"
}
Errores de tarea
Una tarea creada por Meshy puede fallar mientras se ejecuta. Su status pasa a ser FAILED, Meshy reembolsa sus créditos, y task_error explica el motivo.
El task_error de una tarea fallida tiene estos campos:
- Name
- type
- Type
- string
- Description
La categoría del error. Siempre está presente en una tarea fallida. Úsala para decidir si reintentar. Consulta Tipos de error.
- Name
- message
- Type
- string
- Description
Una descripción del error legible para humanos. Siempre está presente en una tarea fallida.
- Name
- code
- Type
- string
- Opcional
- Description
Un problema específico y documentado sobre el que puedes actuar. Presente cuando Meshy tiene más detalles. Consulta Códigos de error. Meshy puede añadir códigos, así que gestiona un código que no reconozcas según su
type.
- Name
- doc_url
- Type
- string
- Opcional
- Description
Un enlace a la entrada del código en esta página, que indica qué hacer. Presente cuando
codeestá presente.
Error with details
{
"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"
}
}
Error without details
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "FAILED",
"task_error": {
"type": "server_error",
"message": "An internal error occurred. Please retry."
}
}
Tipos de error
type es la categoría general del fallo. Úsalo para decidir qué hacer a continuación.
- Name
invalid_input- Description
Algo está mal con la entrada que enviaste. Lee
codeymessage, corrige la entrada y crea una nueva tarea.
- Name
timeout- Description
La tarea superó un límite de tiempo del lado del servidor, ya sea de procesamiento o de espera en la cola, y falló. Meshy reembolsa sus créditos. Esto suele ser temporal. Crea la tarea de nuevo y, si sigue fallando, prueba con una entrada más sencilla.
- Name
service_unavailable- Description
El servicio no estuvo disponible temporalmente. Espera un momento y luego crea la tarea de nuevo.
- Name
server_error- Description
Algo salió mal del lado de Meshy mientras se ejecutaba la tarea. Crea la tarea de nuevo. Si sigue fallando, contacta con soporte indicando el ID de la tarea.
Códigos de error
Cuando code está presente, indica uno de los siguientes problemas.
image_too_complex
La imagen de entrada o el prompt describe un sujeto demasiado complejo geométricamente para la generación 3D.
Por ejemplo:
- Pilas densas de objetos pequeños, como una caja llena de fruta o una pila de libros
- Patrones repetitivos intrincados, como estructuras de celosía, andamios o mallas de alambre
- Edificios complejos, como edificios de varios pisos con muchas ventanas y balcones
- Varios objetos distintos en una sola imagen, en lugar de un único sujeto
Es probable que estas entradas sean demasiado complejas:




Para solucionarlo, prueba una o varias de las siguientes opciones:
- Usa un solo objeto por imagen. Meshy funciona mejor con un único sujeto claro, así que no incluyas varios objetos separados en la misma imagen o prompt.
- Simplifica tu sujeto. Por ejemplo, usa un jarrón simple en lugar de un jarrón lleno de docenas de flores.
- Evita las escenas. Es probable que edificios completos, manzanas de ciudad, habitaciones amuebladas y paisajes sean demasiado. Concéntrate en un solo objeto.
- Evita las estructuras repetitivas densas. Los andamios, las mallas de alambre, las celosías y las pilas de objetos pequeños son desencadenantes comunes.
model_missing_uv
Enviaste un modelo para texturizado con enable_original_uv establecido en true, pero el modelo no tiene coordenadas UV. Las coordenadas UV definen cómo se envuelve una textura 2D sobre la superficie 3D.

Para solucionarlo, haz una de las siguientes acciones:
- Para conservar la propia distribución UV de tu modelo, por ejemplo para una colocación personalizada de las costuras, agrega UVs al modelo en tu software 3D. Compruébalas en su editor de UV y, luego, sube el modelo de nuevo. Los archivos STL no pueden almacenar UVs, así que usa GLB, FBX u OBJ.
- Si no necesitas tu propia distribución, o no estás seguro, omite
enable_original_uvo establécelo enfalse. Meshy entonces crea una distribución UV para el modelo. Las nuevas UVs cubren bien el modelo, pero no puedes controlar dónde van las costuras de la textura.
model_insufficient_uv
El modelo tiene coordenadas UV, pero cubren muy poco del espacio UV para texturizar bien. Esto ocurre a menudo con modelos cuyo exportador escribió UVs de marcador de posición o colapsadas sin un desdoblado adecuado.

Para solucionarlo, haga una de las siguientes acciones:
- Para conservar su propia distribución UV, vuelva a desdoblar las UVs del modelo en su software 3D. Distribuya las islas por todo el espacio UV en lugar de un pequeño rincón de este.
- Si no necesita su propia distribución, omita
enable_original_uvo configúrelo enfalse. Meshy entonces crea una nueva distribución UV. Perderá la ubicación de sus costuras, pero las nuevas UVs cubren suficiente espacio para texturizar.
model_missing_texture
El modelo de entrada de una tarea de Multi-Color Print no tiene ningún color que Meshy pueda dividir en colores de impresión. Meshy construye un 3MF multicolor a partir de los colores del modelo, de modo que una malla blanca lisa no ofrece nada con lo que trabajar. Por ejemplo, una vista previa de Texto a 3D o Imagen a 3D que nunca se texturizó no tiene color. Tampoco lo tiene la salida de Reparar imprimibilidad, ni una tarea de Auto Split que no conservó la textura.
Lo que cuenta como color depende del style que solicitaste:
realisticmuestrea la textura de color base a través de las UV del modelo. Necesita una única textura de color base, y UV en cada parte de la malla.cartoonaplana los colores por cara. Acepta una textura de color base en cualquier parte, o colores por vértice (COLOR_0).
Meshy rechaza un modelo que no tenga ni textura de color base ni colores de vértice para ambos estilos, en lugar de dejar que cartoon lo convierta en una impresión de un solo color.
Meshy rechaza la mayoría de estas solicitudes antes de crear la tarea, con un 400 y la misma explicación. Normalmente solo obtienes este código cuando Meshy no puede comprobar la entrada de antemano. Por ejemplo, Meshy verifica una carga de .fbx solo después de que la tarea la convierte.
Para solucionarlo, usa la opción que se ajuste a tu modelo:
- Texturiza primero el modelo. Ejecuta Retexturizar sobre él, o genéralo con una tarea de refine de Texto a 3D o una tarea de Imagen a 3D con
should_texture: true. Luego envía esa tarea comoinput_task_id. - Para un modelo con colores de vértice, como un escaneo por fotogrametría o una malla pintada a mano, usa
style: "cartoon", que leeCOLOR_0. - Para un modelo parcialmente texturizado o con múltiples texturas con
realistic, da a cada parte de la malla UV y la misma textura de color base única. Para hacerlo, texturiza las partes restantes, o fusiona las texturas en un único atlas. También puedes cambiar astyle: "cartoon".
textured_split_refused
Una tarea de Auto Split con keep_texture: true no puede conservar la textura del modelo de entrada en las partes. Por ejemplo, el modelo no tiene UVs, o su textura no tiene espacio para las nuevas caras que crean los cortes. Meshy reembolsa los créditos.
Para solucionarlo, envía la solicitud de nuevo sin keep_texture, o con keep_texture: false. Las partes se devuelven entonces con un color plano cada una.
invalid_input
La entrada no pasó una verificación, y no aplica ningún código más específico. message indica el motivo.
Por ejemplo:
- Un archivo de modelo vacío o corrupto
- Una variante no admitida de un formato de archivo, como un archivo FBX en ASCII o un archivo GLB comprimido con meshopt
- Un modelo cargado sin objetos 3D válidos, por ejemplo un archivo que solo contiene armaduras, cámaras o luces
- Contenido que no pasa los filtros de seguridad
Para solucionarlo, lee message para conocer el problema específico. Comprueba que tus archivos de entrada y parámetros cumplan los requisitos del endpoint.
moderation_blocked
Los filtros de seguridad rechazaron tu prompt o tus imágenes de referencia. Los filtros verifican el texto y las imágenes en conjunto.
Para solucionarlo, haz una o ambas de las siguientes acciones:
- Reformula el prompt para eliminar descripciones sugerentes o sensibles.
- Cambia las imágenes de referencia que muestren contenido que los filtros podrían bloquear.
moderation_unavailable
Tipo: server_error. La moderation de contenido no estuvo disponible temporalmente, por lo que Meshy marcó la tarea como fallida en lugar de omitir la verificación. No hay nada incorrecto en tu contenido.
Para solucionarlo, crea la tarea nuevamente.
timeout
La tarea superó un límite de tiempo del lado del servidor, ya sea por procesamiento o por espera en la cola, por lo que Meshy la marcó como fallida y reembolsó sus créditos. Una carga alta, o una entrada demasiado compleja para terminar a tiempo, puede causar esto.
Esto es diferente de un timeout en tu propio código. Si tu cliente dejó de esperar, la tarea sigue en ejecución. Consulta Cuánto tiempo esperar.
Para solucionarlo, sigue estos pasos:
- Crea la tarea de nuevo. Los timeouts suelen ser temporales, y una nueva tarea podría tener éxito.
- Si sigue fallando, simplifica tu entrada, por ejemplo reduciendo el detalle en tu imagen o prompt. Para entradas más difíciles de procesar, consulta
image_too_complex.
queue_timeout
Tipo: timeout. La tarea esperó demasiado tiempo en la cola sin comenzar, por lo que Meshy la marcó como fallida y devolvió los créditos cobrados por ella. Tu entrada no causó este error.
Para solucionarlo, crea la tarea de nuevo.
format_conversion_failed
Meshy generó el modelo, pero la conversión a un formato que solicitaste falló.
Para solucionarlo, sigue estos pasos:
- Crea la tarea de nuevo.
- Si un formato sigue fallando, solicita un formato diferente que se ajuste a tus necesidades.
Buenas prácticas
- Reintenta las tareas fallidas. Para una tarea fallida con
timeout,service_unavailableoserver_error, crea una nueva tarea con retroceso exponencial. - No crees una nueva tarea cuando tu propia solicitud agote el tiempo de espera. Es posible que la primera tarea todavía se esté ejecutando, así que comprueba si existe antes de crear otra. Consulta Cuánto tiempo esperar.
- Registra los ID de las tareas. Incluye el ID cuando te pongas en contacto con soporte.
- Comprueba las entradas antes de enviarlas. Asegúrate de que las imágenes y los modelos cumplan con los requisitos de formato del endpoint.
- Llama a la API desde tu servidor. El código que se ejecuta en un navegador expone tu clave de API a cualquiera que abra la página.