Come correggere gli errori 429 e di limite di frequenza dell'API di Meshy

Se la tua integrazione sta riscontrando errori 429, RateLimitExceeded o NoMoreConcurrentTasks quando chiama l'API di Meshy, questa guida spiega perché questi limiti esistono e come progettare la tua integrazione per lavorare nel loro rispetto.

L'API di Meshy si trova davanti a risorse di calcolo GPU condivise utilizzate per generare modelli 3D, texture e asset correlati. I limiti di frequenza e i limiti di concorrenza proteggono questa infrastruttura condivisa, in modo che la qualità della generazione e i tempi di consegna restino costanti per ogni utente della piattaforma. Ogni account, in base al proprio piano attuale, ha un numero massimo di richieste che può effettuare in un dato intervallo di tempo e un numero massimo di attività di generazione che può avere in esecuzione (in coda o in corso) contemporaneamente.

Esistono due limiti distinti, e funzionano in modo diverso:

• Limite di frequenza delle richieste (429 / RateLimitExceeded): questo limita quante chiamate API (ad esempio creazione di attività, polling dello stato) puoi effettuare al minuto. Superarlo significa che stai chiamando l'API con troppa frequenza, indipendentemente da quante attività siano effettivamente in esecuzione.

• Limite di concorrenza/coda (NoMoreConcurrentTasks): questo limita quante attività di generazione puoi avere in coda o in elaborazione allo stesso tempo. Superarlo significa che hai già raggiunto il numero massimo di attività attive e devi attendere che una finisca prima di inviarne un'altra.

Controlla i limiti attuali di richieste e concorrenza del tuo piano nella tua dashboard di Meshy, poiché possono variare in base al livello del piano.

Quando ricevi una risposta 429 o RateLimitExceeded, non ritentare immediatamente la stessa richiesta. Invece:

• Usa il backoff esponenziale: attendi un breve intervallo, poi raddoppialo a ogni successivo fallimento, fino a un massimo ragionevole.

• Aggiungi del jitter (una piccola variazione casuale) al tuo intervallo di backoff, in modo che più worker nel tuo sistema non ritentino tutti nello stesso istante.

• Rispetta eventuali header Retry-After o di limite di frequenza restituiti nella risposta, se presenti, invece di stabilire un tempo di attensa a caso.

• Limita il numero di tentativi per richiesta, in modo che un fallimento persistente non vada in loop all'infinito.

Un errore NoMoreConcurrentTasks significa che hai già raggiunto il tetto di attività attive del tuo account. Per evitarlo in produzione:

• Mantieni una coda locale o uno scheduler di attività nella tua applicazione che invii una nuova attività di generazione solo quando una precedente è completata o il numero di attività attive scende sotto il limite.

• Interroga lo stato delle attività (o usa webhook, se supportati nel tuo flusso di lavoro) per sapere quando si libera uno slot, invece di inviare in modo speculativo.

• Raggruppa in batch e limita la frequenza dei lavori di generazione in blocco invece di lanciare tutte le richieste in una volta: questo uniforma sia la frequenza delle richieste sia il numero di attività concorrenti.

• Integra nel tuo sistema monitoraggio/avvisi, in modo che un picco di errori 429/NoMoreConcurrentTasks sia visibile prima che influisca sui tuoi utenti.

L'API di Meshy attualmente non supporta un "retry" integrato di una generazione esistente per i piani individual o studio: se un risultato non soddisfa le tue aspettative, devi inviare una nuova richiesta di generazione, che consuma crediti normalmente. Quando la tua pipeline automatica gestisce errori temporanei (come un 429), assicurati che la logica di retry invii nuovamente solo la richiesta originale dopo un backoff, senza creare attività di generazione duplicate ogni volta.

Se hai implementato il backoff e una gestione delle code consapevole della concorrenza e continui comunque a raggiungere costantemente i limiti di frequenza o di concorrenza, in genere è un segno che le esigenze di throughput della tua integrazione hanno superato i limiti del tuo piano attuale. Controlla nella dashboard le tolleranze di richieste e concorrenza del tuo piano attuale e valuta un upgrade o di contattare il team di vendita di Meshy per un accesso API di livello enterprise se hai bisogno di un throughput sostenuto più elevato.

Significa che hai superato il numero di richieste API consentite in un dato intervallo di tempo per il tuo piano. Riduci la frequenza delle richieste e usa il backoff esponenziale prima di ritentare.

Significa che hai già raggiunto il numero massimo di attività di generazione in coda o in corso per il tuo account. Attendi che un'attività esistente finisca, o riduci il numero di attività che invii contemporaneamente, prima di inviarne altre.

Controlla nella tua dashboard di Meshy i limiti associati al tuo piano attuale, poiché possono variare tra i livelli di piano.

No, non per i piani individual o studio: una generazione fallita o insoddisfacente deve essere inviata nuovamente come nuova richiesta, che utilizza crediti normalmente. I clienti enterprise dovrebbero contattare l'ufficio vendite per informazioni sulla funzionalità di retry.

Implementa una coda locale che limiti l'invio per rimanere sotto il tuo limite di concorrenza, aggiungi un backoff esponenziale con jitter per le risposte 429 e monitora la frequenza degli errori per poter intervenire prima che impattino sui tuoi utenti.

Se hai già implementato il backoff e una gestione delle code consapevole della concorrenza e raggiungi comunque regolarmente questi limiti, è probabile che il tuo utilizzo abbia superato il piano attuale: controlla la dashboard o contatta l'ufficio vendite per un piano con throughput più elevato.

• Come si usa l'API di Meshy?

• L'API di Meshy supporta il retry per le generazioni?