lowpoly se retira el 30 oct 2026. meshy-7 se retira como modelo de generación 3D el 31 dic 2026; como modelo de texturas sigue disponible. Cambia de modelo antes de estas fechas para evitar errores en las solicitudes. Ver todas las obsolescencias

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 400 para 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_PROGRESS devuelve 409, 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, o CANCELED), 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 422 cuando 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 code está 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 code y message, 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:

A crate of mixed berriesAn intricate cathedral ceilingA building under construction with scaffoldingA honeycomb lattice sphere

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.

No UVs vs Good UVs

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_uv o establécelo en false. 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.

Insufficient UVs vs Good UVs

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_uv o configúrelo en false. 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:

  • realistic muestrea 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.
  • cartoon aplana 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 como input_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 lee COLOR_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 a style: "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:

  1. Crea la tarea de nuevo. Los timeouts suelen ser temporales, y una nueva tarea podría tener éxito.
  2. 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:

  1. Crea la tarea de nuevo.
  2. 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_unavailable o server_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.