Pular para o conteúdo principal

Como Corrigir Erros 429 e Limites de Taxa da API Meshy

Limites de Taxa da API Meshy: Corrigir Erros 429

Sumário

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

Por que existem limites de taxa

A API Meshy fica na frente da capacidade computacional de GPU compartilhada usada para gerar modelos 3D, texturas e recursos relacionados. Limites de taxa e limites de concorrência protegem essa infraestrutura compartilhada para que a qualidade da geração e o tempo de processamento permaneçam consistentes para todos os usuários da plataforma. Cada conta, com base em 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.

Limite de requisições vs. limite de fila/concorrência

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

  • Limite de taxa de requisições (429 / RateLimitExceeded): define quantas chamadas de API (por exemplo, criação de tarefas e 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): define 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 painel da Meshy, pois eles podem variar conforme o nível do plano.

Estratégia de espera para erros 429

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

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

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

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

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

Planejando em torno dos limites de concorrência

Um erro NoMoreConcurrentTasks significa que você já atingiu o teto de tarefas ativas da sua conta. Para evitar isso 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 a anterior for concluída ou quando sua contagem de tarefas ativas ficar abaixo do limite.

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

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

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

Reenviando gerações com falha ou insatisfatórias

No momento, a API Meshy não oferece suporte a uma "nova tentativa" integrada de uma geração existente para planos individual ou studio — se um resultado não atender às suas expectativas, você envia uma nova solicitação de geração, o que consome créditos normalmente. Quando seu pipeline automatizado lidar com erros transitórios (como um 429), certifique-se de que sua lógica de nova tentativa reenvie apenas a solicitação original após um intervalo de espera, sem criar tarefas de geração duplicadas a cada tentativa.

Quando considerar atualizar seu plano

Se você já implementou a espera (backoff) e o enfileiramento com reconhecimento de concorrência e mesmo assim continua atingindo os limites de taxa ou de concorrência de forma consistente, isso geralmente é um sinal de que as necessidades de throughput da sua integração superaram os limites do seu plano atual. Verifique no seu painel as permissões de requisições e de concorrência do seu plano atual e considere fazer upgrade ou entrar em contato com a equipe de vendas da Meshy para saber mais sobre acesso à API em nível empresarial, caso você precise de um throughput mais alto e sustentado.

Perguntas Frequentes

1. O que significa um erro 429 ou RateLimitExceeded?

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

2. O que significa NoMoreConcurrentTasks?

Significa que você já atingiu 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.

3. Como descubro os limites de taxa e concorrência da minha conta?

Consulte seu painel da Meshy para ver os limites associados ao seu plano atual, pois eles podem variar entre os níveis de plano.

4. A Meshy oferece tentativas automáticas para tarefas de geração?

Não, nem para planos individuais nem para planos studio — uma geração com falha ou insatisfatória deve ser reenviada como uma nova requisição, o que consome créditos normalmente. Clientes Enterprise devem entrar em contato com a equipe de vendas para saber sobre a funcionalidade de novas tentativas.

5. Qual é a melhor forma de evitar esses erros em um pipeline de produção?

Implemente uma fila local que limite os envios para permanecer abaixo do seu limite de concorrência, adicione espera exponencial com jitter para quaisquer respostas 429 e monitore as taxas de erro para que você possa reagir antes que elas afetem seus usuários.

6. Quando devo atualizar meu plano por causa dos limites de taxa?

Se você já implementou espera e enfileiramento com reconhecimento de concorrência e ainda atinge esses limites regularmente, seu uso provavelmente superou seu plano atual — verifique seu painel ou entre em contato com a equipe de vendas sobre um plano com maior taxa de transferência.


Artigos relacionados

Isso respondeu à sua pergunta?