Como Corrigir Erros 429 e de Limite de Taxa na API do Meshy

Se a sua integração está recebendo erros 429, RateLimitExceeded ou NoMoreConcurrentTasks ao chamar a API do Meshy, este guia explica por que esses limites existem e como projetar sua integração para funcionar dentro deles.

A API do Meshy fica à frente de uma capacidade computacional de GPU compartilhada usada para gerar modelos 3D, texturas e ativos relacionados. Os limites de taxa e os limites de concorrência protegem essa infraestrutura compartilhada para que a qualidade da geração e o tempo de resposta permaneçam consistentes para todos os usuários da plataforma. Cada conta, com base no seu plano atual, tem um número máximo de requisições que pode fazer em uma determinada janela de tempo e um número máximo de tarefas de geração que pode ter em execução (na fila ou em andamento) ao mesmo tempo.

Existem dois limites distintos, e eles falham de maneiras diferentes:

• Limite de taxa de requisições (429 / RateLimitExceeded): este limite restringe quantas chamadas de API (por exemplo, criação de tarefas, consulta de status) você pode fazer por minuto. Excedê-lo significa que você está chamando a API com muita frequência, independentemente de quantas tarefas estão realmente em execução.

• Limite de concorrência/fila (NoMoreConcurrentTasks): este limite restringe quantas tarefas de geração você pode ter na fila ou em processamento ao mesmo tempo. Excedê-lo significa que você já tem o número máximo de tarefas ativas e precisa esperar que uma termine antes de enviar outra.

Verifique os limites atuais de requisições e concorrência do seu plano no seu painel do Meshy, pois eles podem variar conforme a categoria do plano.

Quando você receber uma resposta 429 ou RateLimitExceeded, não tente repetir a mesma requisição imediatamente. Em vez disso:

• Use backoff exponencial: aguarde um intervalo curto e, a cada falha subsequente, dobre esse intervalo, até um máximo razoável.

• Adicione jitter (um pequeno deslocamento aleatório) ao seu intervalo de backoff para que vários workers no seu sistema não tentem novamente no mesmo instante.

• Respeite quaisquer cabeçalhos Retry-After ou de limite de taxa retornados na resposta, se presentes, em vez de adivinhar um tempo de espera.

• Limite o número de tentativas por requisição para que uma falha persistente não entre em loop indefinidamente.

Um erro NoMoreConcurrentTasks significa que você já atingiu o teto de tarefas ativas da sua conta. Para evitar atingi-lo em produção:

• Mantenha uma fila local ou um agendador de tarefas na sua própria aplicação que só envie uma nova tarefa de geração quando uma anterior for concluída ou quando sua contagem de tarefas ativas cair abaixo do limite.

• Consulte o status das tarefas (ou use webhooks, se houver suporte no seu fluxo de trabalho) para saber quando uma vaga é liberada, em vez de enviar requisições especulativamente.

• Agrupe e regule trabalhos de geração em lote em vez de disparar todas as requisições de uma vez — isso suaviza tanto sua taxa de requisições quanto a contagem de tarefas simultâneas.

• Implemente monitoramento/alertas do seu lado para que um aumento nos erros 429/NoMoreConcurrentTasks fique visível antes de afetar seus usuários.

Atualmente, a API do Meshy não oferece suporte a uma repetição integrada de uma geração existente para planos individuais ou de estúdio — se um resultado não atender às suas expectativas, você envia uma nova requisição de geração, que consome créditos normalmente. Quando seu pipeline automatizado lida com erros transitórios (como um 429), certifique-se de que sua lógica de repetição esteja apenas reenviando a requisição original após um período de espera, e não criando tarefas de geração duplicadas a cada vez.

Se você já implementou backoff e filas com controle de concorrência e ainda está atingindo consistentemente os limites de taxa ou de concorrência, isso geralmente é um sinal de que as necessidades de capacidade da sua integração ultrapassaram os limites do seu plano atual. Verifique no seu painel os limites de requisições e concorrência do seu plano atual e considere fazer upgrade ou entrar em contato com a equipe de vendas do Meshy sobre acesso à API de nível empresarial, se você precisar de capacidade sustentada mais alta.

Significa que você excedeu o número de requisições de API permitidas em uma determinada janela de tempo para o seu plano. Reduza sua taxa de requisições e use backoff exponencial antes de tentar novamente.

Significa que você já tem o número máximo de tarefas de geração na fila ou em andamento para a sua conta. Aguarde a conclusão de uma tarefa existente ou reduza quantas tarefas você envia de uma vez, antes de enviar mais.

Verifique no seu painel do Meshy os limites associados ao seu plano atual, pois eles podem variar entre as categorias de plano.

Não, não para planos individuais ou de estúdio — uma geração com falha ou insatisfatória deve ser reenviada como uma nova requisição, que usa créditos normalmente. Clientes empresariais devem entrar em contato com o setor de vendas sobre a funcionalidade de repetição.

Implemente uma fila local que regule os envios para ficar abaixo do seu limite de concorrência, adicione backoff exponencial com jitter para qualquer resposta 429 e monitore as taxas de erro para poder reagir antes que elas impactem seus usuários.

Se você já implementou backoff e filas com controle de concorrência e ainda atinge regularmente esses limites, seu uso provavelmente ultrapassou o seu plano atual — verifique seu painel ou entre em contato com o setor de vendas sobre um plano de maior capacidade.

• Como usar a API do Meshy?

• A API do Meshy oferece suporte a repetição para gerações?