Como Corrigir Erros 429 e de Limite de Taxa da API Meshy

Se a sua integração está a deparar-se com erros 429, RateLimitExceeded ou NoMoreConcurrentTasks ao chamar a API do Meshy, este guia explica porque é que estes limites existem e como desenhar a sua integração para funcionar dentro deles.

A API do Meshy está à frente de recursos partilhados de computação em GPU utilizados para gerar modelos 3D, texturas e ativos relacionados. Os limites de taxa e os limites de concorrência protegem essa infraestrutura partilhada para que a qualidade da geração e o tempo de resposta se mantenham consistentes para todos os utilizadores da plataforma. Cada conta, com base no seu plano atual, tem um número máximo de pedidos que pode fazer num determinado intervalo de tempo e um número máximo de tarefas de geração que pode ter em execução (em fila ou em curso) ao mesmo tempo.

Existem dois limites distintos e falham de formas diferentes:

• Limite de taxa de pedidos (429 / RateLimitExceeded): este limita o número de chamadas à API (por exemplo, criação de tarefas, consulta de estado) que pode fazer por minuto. Excedê-lo significa que está a chamar a API com demasiada frequência, independentemente do número de tarefas realmente em execução.

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

Consulte os limites atuais de pedidos e de concorrência do seu plano no painel do Meshy, pois estes podem variar consoante o nível do plano.

Quando recebe uma resposta 429 ou RateLimitExceeded, não repita imediatamente o mesmo pedido. Em vez disso:

• Use backoff exponencial: espere um curto intervalo de tempo e duplique-o em cada falha subsequente, até um máximo razoável.

• Adicione jitter (um pequeno desvio aleatório) ao intervalo de backoff para que vários trabalhadores no seu sistema não repitam todos no mesmo instante.

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

• Limitar o número de repetições por pedido, para que uma falha persistente não entre em ciclo infinito.

Um erro NoMoreConcurrentTasks significa que já atingiu o limite máximo 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ó submeta uma nova tarefa de geração quando uma anterior terminar ou quando o seu número de tarefas ativas descer abaixo do limite.

• Consulte o estado das tarefas (ou use webhooks, se suportados no seu fluxo de trabalho) para saber quando um espaço fica livre, em vez de submeter especulativamente.

• Agrupe e limite os trabalhos de geração em massa em vez de disparar todos os pedidos de uma vez — isto suaviza tanto a sua taxa de pedidos como a contagem de tarefas concorrentes.

• Implemente monitorização/alertas do seu lado para que um pico de erros 429/NoMoreConcurrentTasks seja visível antes de afetar os seus utilizadores.

A API do Meshy não suporta atualmente uma "repetição" integrada de uma geração existente para planos individuais ou studio — se um resultado não corresponde às suas expectativas, deve submeter um novo pedido de geração, que consome créditos normalmente. Quando o seu pipeline automatizado trata erros transitórios (como um 429), certifique-se de que a sua lógica de repetição apenas reenvia o pedido original após o backoff, sem criar tarefas de geração duplicadas de cada vez.

Se já implementou backoff e uma fila consciente da concorrência e ainda está constantemente a atingir os limites de taxa ou de concorrência, isso normalmente é um sinal de que as necessidades de débito da sua integração ultrapassaram os limites do seu plano atual. Consulte o seu painel para verificar os limites de pedidos e de concorrência do seu plano atual e considere fazer upgrade ou contactar a equipa de vendas do Meshy sobre acesso à API de nível empresarial, se precisar de um débito superior sustentado.

Significa que excedeu o número de pedidos à API permitido num determinado intervalo de tempo para o seu plano. Reduza a sua taxa de pedidos e use backoff exponencial antes de repetir.

Significa que já tem o número máximo de tarefas de geração em fila ou em curso para a sua conta. Espere que uma tarefa existente termine, ou reduza quantas tarefas submete de uma vez, antes de submeter mais.

Consulte o painel do Meshy para verificar os limites associados ao seu plano atual, pois estes podem diferir entre níveis de plano.

Não, não para planos individuais ou studio — uma geração falhada ou insatisfatória tem de ser ressubmetida como um novo pedido, que utiliza créditos normalmente. Os clientes empresariais devem contactar as vendas sobre a funcionalidade de repetição.

Implemente uma fila local que limite as submissões para se manter abaixo do seu limite de concorrência, adicione backoff exponencial com jitter para quaisquer respostas 429 e monitorize as taxas de erro para poder reagir antes que afetem os seus utilizadores.

Se já implementou backoff e uma fila consciente da concorrência e ainda atinge regularmente estes limites, é provável que a sua utilização tenha ultrapassado o seu plano atual — consulte o seu painel ou contacte as vendas sobre um plano com maior débito.

• Como Utilizar a API do Meshy?

• A API do Meshy Suporta Repetição para Gerações?