Cómo corregir los errores 429 y de límite de tasa de la API de Meshy

Si tu integración está recibiendo errores 429, RateLimitExceeded o NoMoreConcurrentTasks al llamar a la API de Meshy, esta guía explica por qué existen estos límites y cómo diseñar tu integración para trabajar dentro de ellos.

La API de Meshy se encuentra frente a cómputo de GPU compartido que se utiliza para generar modelos 3D, texturas y recursos relacionados. Los límites de tasa y los topes de concurrencia protegen esa infraestructura compartida para que la calidad de generación y el tiempo de entrega se mantengan consistentes para cada usuario de la plataforma. Cada cuenta, según su plan actual, tiene un número máximo de solicitudes que puede realizar en un período de tiempo determinado y un número máximo de tareas de generación que puede tener en ejecución (en cola o en progreso) al mismo tiempo.

Existen dos límites distintos, y fallan de manera diferente:

• Límite de tasa de solicitudes (429 / RateLimitExceeded): este limita cuántas llamadas a la API (por ejemplo, creación de tareas, sondeo de estado) puedes hacer por minuto. Superarlo significa que estás llamando a la API con demasiada frecuencia, independientemente de cuántas tareas estén realmente en ejecución.

• Límite de concurrencia / cola (NoMoreConcurrentTasks): este limita cuántas tareas de generación puedes tener en cola o procesándose al mismo tiempo. Superarlo significa que ya tienes el número máximo de tareas activas y necesitas esperar a que una finalice antes de enviar otra.

Consulta los límites actuales de solicitudes y concurrencia de tu plan en tu panel de Meshy, ya que pueden variar según el nivel del plan.

Cuando recibas una respuesta 429 o RateLimitExceeded, no reintentes de inmediato la misma solicitud. En su lugar:

• Usa backoff exponencial: espera un intervalo corto y luego duplícalo en cada fallo subsiguiente, hasta un máximo razonable.

• Añade jitter (un pequeño desfase aleatorio) a tu intervalo de backoff para que varios workers de tu sistema no reintenten todos en el mismo instante.

• Respeta cualquier encabezado Retry-After o de límite de tasa devuelto en la respuesta, si está presente, en lugar de adivinar un tiempo de espera.

• Limita el número de reintentos por solicitud para que un fallo persistente no entre en un bucle infinito.

Un error NoMoreConcurrentTasks significa que ya estás en el techo de tareas activas de tu cuenta. Para evitar alcanzarlo en producción:

• Mantén una cola local o un planificador de trabajos en tu propia aplicación que solo envíe una nueva tarea de generación cuando una anterior se complete o cuando tu conteo activo baje del límite.

• Sondea el estado de las tareas (o usa webhooks, si son compatibles con tu flujo de trabajo) para saber cuándo se libera un espacio, en lugar de enviar de forma especulativa.

• Agrupa y regula los trabajos de generación masiva en lugar de disparar todas las solicitudes a la vez; esto suaviza tanto tu tasa de solicitudes como tu conteo de tareas concurrentes.

• Incorpora monitoreo/alertas de tu lado para que un pico de errores 429/NoMoreConcurrentTasks sea visible antes de que afecte a tus usuarios.

La API de Meshy actualmente no admite un "retry" integrado de una generación existente para los planes individual o studio: si un resultado no cumple tus expectativas, envías una nueva solicitud de generación, que consume créditos de forma normal. Cuando tu pipeline automatizado maneja errores transitorios (como un 429), asegúrate de que tu lógica de reintentos solo reenvíe la solicitud original después de aplicar backoff, sin crear tareas de generación duplicadas cada vez.

Si has implementado backoff y colas conscientes de la concurrencia y aun así alcanzas consistentemente los límites de tasa o concurrencia, eso suele ser una señal de que las necesidades de rendimiento de tu integración han superado los límites de tu plan actual. Consulta en tu panel las asignaciones de solicitudes y concurrencia de tu plan actual, y considera actualizar o contactar al equipo de ventas de Meshy sobre acceso a la API a nivel empresarial si necesitas un rendimiento sostenido mayor.

Significa que has excedido el número de solicitudes a la API permitidas dentro de un período de tiempo determinado para tu plan. Reduce tu tasa de solicitudes y usa backoff exponencial antes de reintentar.

Significa que ya tienes el número máximo de tareas de generación en cola o en progreso para tu cuenta. Espera a que una tarea existente finalice, o reduce cuántas tareas envías a la vez, antes de enviar más.

Consulta tu panel de Meshy para ver los límites asociados a tu plan actual, ya que pueden diferir entre niveles de plan.

No, no para los planes individual o studio: una generación fallida o insatisfactoria debe reenviarse como una nueva solicitud, que usa créditos de forma normal. Los clientes empresariales deben contactar a ventas sobre la funcionalidad de reintentos.

Implementa una cola local que regule los envíos para mantenerte por debajo de tu límite de concurrencia, añade backoff exponencial con jitter para cualquier respuesta 429, y monitorea las tasas de error para poder reaccionar antes de que impacten a tus usuarios.

Si ya has implementado backoff y colas conscientes de la concurrencia y aun así alcanzas regularmente estos límites, es probable que tu uso haya superado tu plan actual: consulta tu panel o contacta a ventas sobre un plan de mayor rendimiento.

• ¿Cómo uso la API de Meshy?

• ¿La API de Meshy admite reintentos para generaciones?