Errori
Scopri perché una richiesta o un task sono falliti, e cosa fare in seguito. Una richiesta può fallire immediatamente con un errore HTTP, e un task può fallire successivamente con un task_error.
Errori della richiesta
Meshy restituisce questi errori immediatamente, quando rifiuta una richiesta. Per scoprire cosa è andato storto, controlla il codice di stato HTTP e il campo message.
Formato della risposta
La risposta di errore ha un campo message che descrive cosa è andato storto:
- Name
- message
- Type
- string
- Description
Una breve descrizione dell'errore.
Codici di stato
- Name
2xx- Description
Successo.
- Name
200 - OK- Description
La richiesta ha funzionato.
- Name
202 - Accepted- Description
Meshy ha accettato la richiesta, e l'elaborazione non è ancora terminata. Ad esempio, una richiesta che crea un task restituisce
202.
- Name
4xx- Description
Qualcosa non va nella richiesta o nel tuo account. Ogni stato indica cosa fare.
- Name
400 - Bad Request- Description
La richiesta non è valida, spesso perché manca un parametro obbligatorio o un parametro è malformato.
- Name
401 - Unauthorized- Description
La chiave API manca, non è valida, o non può accedere a questo endpoint. Vedi Autenticazione.
- Name
402 - Payment Required- Description
L'account della chiave API non ha crediti sufficienti per la richiesta. Nel piano Free, la maggior parte delle richieste che creano un task restituiscono anche
402.
- Name
403 - Forbidden- Description
Non sei autorizzato a effettuare questa richiesta, ad esempio per uno di questi motivi:
- La richiesta proviene da un indirizzo esterno alla lista consentita di IP della chiave API.
- Il filtraggio IP della tua organizzazione ha bloccato i file di un task durante la lettura.
- L'endpoint non è disponibile nel tuo piano.
- La moderation dei contenuti ha bloccato l'input. Alcuni endpoint restituiscono
400per questo caso; ogni pagina dell'endpoint elenca i propri codici. - La chiave API appartiene a un membro del team che non è più attivo nel team.
- L'account è bannato.
- Name
404 - Not Found- Description
La risorsa non esiste. Ad esempio, ottenere un task con un ID che non esiste restituisce
404.
- Name
409 - Conflict- Description
La risorsa esiste, ma il suo stato non consente l'operazione. Ad esempio, eliminare un task
IN_PROGRESSrestituisce409, perché Meshy non può rimborsare un task che un worker ha già avviato. Il task continua a essere eseguito. Attendi uno stato finale (SUCCEEDED,FAILED, oCANCELED), poi elimina il task.
- Name
422 - Unprocessable Entity- Description
La richiesta è valida, ma Meshy non può elaborare il suo input. Ad esempio, Rigging restituisce
422quando non riesce a trovare un corpo umanoide nel modello.
- Name
429 - Too Many Requests- Description
Hai inviato troppe richieste, oppure troppi dei tuoi task sono in coda o in esecuzione. Quando la risposta ha un header
Retry-After, attendi quel numero di secondi, poi riprova. Vedi Limiti di velocità.
- Name
5xx- Description
Qualcosa è andato storto dal lato di Meshy. Riprova con un backoff. Se l'errore persiste, controlla la pagina di stato e contattaci su Discord.
Example: 400 Bad Request
{
"message": "Invalid model file extension: .3dm"
}
Errori delle task
Una task creata da Meshy può comunque fallire durante l'esecuzione. Il suo status diventa FAILED, Meshy rimborsa i relativi crediti e task_error spiega il motivo.
Il task_error di una task fallita ha questi campi:
- Name
- type
- Type
- string
- Description
La categoria dell'errore. È sempre presente su una task fallita. Usala per decidere se riprovare. Vedi Tipi di errore.
- Name
- message
- Type
- string
- Description
Una descrizione leggibile dell'errore. È sempre presente su una task fallita.
- Name
- code
- Type
- string
- Opzionale
- Description
Un problema specifico e documentato su cui puoi agire. Presente quando Meshy dispone di maggiori dettagli. Vedi Codici di errore. Meshy potrebbe aggiungere nuovi codici, quindi gestisci un codice che non riconosci in base al suo
type.
- Name
- doc_url
- Type
- string
- Opzionale
- Description
Un link alla voce del codice su questa pagina, che indica cosa fare. Presente quando
codeè presente.
Error with details
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "FAILED",
"task_error": {
"type": "invalid_input",
"code": "image_too_complex",
"message": "The uploaded image is too complex for 3D generation.",
"doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
}
}
Error without details
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "FAILED",
"task_error": {
"type": "server_error",
"message": "An internal error occurred. Please retry."
}
}
Tipi di errore
type è la categoria generale dell'errore. Usala per decidere cosa fare successivamente.
- Name
invalid_input- Description
C'è qualcosa che non va nell'input inviato. Leggi
codeemessage, correggi l'input e crea un nuovo task.
- Name
timeout- Description
Il task ha superato un limite di tempo lato server, per l'elaborazione o per l'attesa in coda, ed è fallito. Meshy rimborsa i relativi crediti. Spesso si tratta di un problema temporaneo. Crea di nuovo il task e, se continua a fallire, prova con un input più semplice.
- Name
service_unavailable- Description
Il servizio era temporaneamente non disponibile. Attendi un momento, poi crea di nuovo il task.
- Name
server_error- Description
Qualcosa è andato storto lato Meshy durante l'esecuzione del task. Crea di nuovo il task. Se continua a fallire, contatta il supporto fornendo l'ID del task.
Codici di errore
Quando code è presente, indica uno dei seguenti problemi.
image_too_complex
L'immagine di input o il prompt descrive un soggetto geometricamente troppo complesso per la generazione 3D.
Ad esempio:
- Mucchi densi di piccoli oggetti, come una cassa piena di frutta o una pila di libri
- Motivi ripetitivi intricati, come strutture a traliccio, impalcature o reti metalliche
- Edifici complessi, come edifici a più piani con molte finestre e balconi
- Diversi oggetti distinti in una sola immagine, anziché un singolo soggetto
Questi input sono probabilmente troppo complessi:




Per risolvere il problema, prova uno o più dei seguenti suggerimenti:
- Usa un solo oggetto per immagine. Meshy funziona al meglio con un soggetto chiaro e unico, quindi non inserire più oggetti separati nella stessa immagine o nello stesso prompt.
- Semplifica il tuo soggetto. Ad esempio, usa un semplice vaso invece di un vaso pieno di decine di fiori.
- Evita le scene. Interi edifici, isolati cittadini, stanze arredate e paesaggi sono probabilmente eccessivi. Concentrati su un singolo oggetto.
- Evita strutture ripetitive dense. Impalcature, reti metalliche, trafori e mucchi di piccoli oggetti sono cause comuni.
model_missing_uv
Hai inviato un modello per la texturizzazione con enable_original_uv impostato su true, ma il modello non ha coordinate UV. Le coordinate UV definiscono come una texture 2D si avvolge sulla superficie 3D.

Per risolvere il problema, effettua una delle seguenti operazioni:
- Per mantenere il layout UV del tuo modello, ad esempio per un posizionamento personalizzato delle cuciture, aggiungi le UV al modello nel tuo software 3D. Controllale nel suo editor UV, quindi carica di nuovo il modello. I file STL non possono memorizzare le UV, quindi usa GLB, FBX o OBJ.
- Se non hai bisogno di un tuo layout, oppure non sei sicuro, ometti
enable_original_uvoppure impostalo sufalse. Meshy creerà quindi un layout UV per il modello. Le nuove UV coprono bene il modello, ma non potrai controllare dove si trovano le cuciture della texture.
model_insufficient_uv
Il modello ha coordinate UV, ma coprono troppo poco dello spazio UV per poter essere texturizzato correttamente. Questo accade spesso con modelli il cui esportatore ha scritto UV segnaposto o collassate senza un corretto unwrap.

Per risolvere il problema, effettua una delle seguenti operazioni:
- Per mantenere il tuo layout UV personale, esegui nuovamente l'unwrap delle UV del modello nel tuo software 3D. Distribuisci le isole nello spazio UV invece di concentrarle in un piccolo angolo.
- Se non hai bisogno di un tuo layout personale, ometti
enable_original_uvoppure impostalo sufalse. Meshy creerà quindi un nuovo layout UV. Perderai il posizionamento delle cuciture originali, ma le nuove UV copriranno uno spazio sufficiente per la texturizzazione.
model_missing_texture
Il modello di input di un'attività Multi-Color Print non ha alcun colore che Meshy possa dividere in colori di stampa. Meshy crea un 3MF multicolore a partire dai colori del modello, quindi una mesh bianca uniforme non offre nulla con cui lavorare. Ad esempio, un'anteprima Testo in 3D o Immagine in 3D che non è mai stata texturizzata non ha colore. Lo stesso vale per l'output di Ripara stampabilità, o per un'attività Auto Split che non ha mantenuto la texture.
Ciò che conta come colore dipende dallo style richiesto:
realisticcampiona la texture del colore base attraverso gli UV del modello. Richiede una singola texture del colore base e UV su ogni parte della mesh.cartoonappiattisce i colori per faccia. Accetta una texture del colore base su qualsiasi parte, oppure colori per vertice (COLOR_0).
Meshy rifiuta un modello privo sia di texture del colore base che di colori dei vertici per entrambi gli stili, invece di lasciare che cartoon lo trasformi in una stampa monocolore.
Meshy rifiuta la maggior parte di queste richieste prima di creare l'attività, restituendo un 400 con la stessa spiegazione. Di solito si riceve questo codice solo quando Meshy non può verificare l'input in anticipo. Ad esempio, Meshy controlla un caricamento .fbx solo dopo che l'attività lo converte.
Per risolvere, usa l'opzione adatta al tuo modello:
- Applica prima la texture al modello. Esegui Retexture su di esso, oppure generalo con un'attività refine di Testo in 3D o un'attività di Immagine in 3D con
should_texture: true. Quindi invia quell'attività comeinput_task_id. - Per un modello con colori per vertice, come una scansione fotogrammetrica o una mesh dipinta a mano, usa
style: "cartoon", che leggeCOLOR_0. - Per un modello parzialmente texturizzato o multi-texture con
realistic, assegna a ogni parte della mesh gli UV e la stessa singola texture del colore base. Per farlo, applica la texture alle parti rimanenti, oppure unisci le texture in un unico atlas. Puoi anche passare astyle: "cartoon".
textured_split_refused
Un task di Auto Split con keep_texture: true non riesce a mantenere la texture del modello di input sulle parti. Ad esempio, il modello non ha UV, oppure la sua texture non ha spazio per le nuove facce create dai tagli. Meshy rimborsa i crediti.
Per risolvere, invia di nuovo la richiesta senza keep_texture, oppure con keep_texture: false. Le parti verranno quindi restituite ciascuna con un colore uniforme.
invalid_input
L'input non ha superato un controllo e non si applica nessun codice più specifico. message indica il motivo.
Ad esempio:
- Un file del modello vuoto o danneggiato
- Una variante non supportata di un formato di file, come un file FBX in formato ASCII o un file GLB compresso con meshopt
- Un modello caricato privo di oggetti 3D validi, ad esempio un file che contiene solo armature, telecamere o luci
- Contenuti che non superano i filtri di sicurezza
Per risolvere, leggi message per individuare il problema specifico. Verifica che i file di input e i parametri rispettino i requisiti dell'endpoint.
moderation_blocked
I filtri di sicurezza hanno rifiutato il tuo prompt o le immagini di riferimento. I filtri controllano il testo e le immagini insieme.
Per risolvere il problema, esegui una o entrambe le seguenti azioni:
- Riformula il prompt per rimuovere descrizioni allusive o sensibili.
- Cambia le immagini di riferimento che mostrano contenuti che i filtri potrebbero bloccare.
moderation_unavailable
Tipo: server_error. La moderation dei contenuti era temporaneamente non disponibile, quindi Meshy ha fatto fallire l'attività anziché saltare il controllo. Non c'è nulla che non va nel tuo contenuto.
Per risolvere il problema, crea nuovamente l'attività.
timeout
Il task ha superato un limite di tempo lato server, per l'elaborazione o per l'attesa in coda, quindi Meshy lo ha contrassegnato come non riuscito e ha rimborsato i relativi crediti. Un carico elevato, oppure un input troppo complesso da completare in tempo, può esserne la causa.
Questo è diverso da un timeout nel tuo codice. Se il tuo client ha smesso di attendere, il task è comunque ancora in esecuzione. Vedi Quanto tempo attendere.
Per risolvere il problema, segui questi passaggi:
- Crea nuovamente il task. I timeout sono spesso temporanei, e un nuovo task potrebbe riuscire.
- Se continua a fallire, semplifica il tuo input, ad esempio riducendo il dettaglio della tua immagine o del tuo prompt. Per gli input più difficili da elaborare, vedi
image_too_complex.
queue_timeout
Tipo: timeout. L'attività è rimasta in coda troppo a lungo senza avviarsi, quindi Meshy l'ha contrassegnata come fallita e ha restituito eventuali crediti addebitati per essa. Il tuo input non ha causato questo errore.
Per risolverlo, crea nuovamente l'attività.
format_conversion_failed
Meshy ha generato il modello, ma la conversione nel formato richiesto non è riuscita.
Per risolvere il problema, segui questi passaggi:
- Crea nuovamente l'attività.
- Se un formato continua a fallire, richiedi un formato diverso che soddisfi le tue esigenze.
Best practices
- Esegui nuovamente i task falliti. Per un task non riuscito con
timeout,service_unavailableoserver_error, crea un nuovo task con backoff esponenziale. - Non creare un nuovo task quando la tua richiesta va in timeout. Il primo task potrebbe essere ancora in esecuzione, quindi verifica se esiste prima di crearne un altro. Consulta Quanto tempo attendere.
- Registra gli ID dei task. Includi l'ID quando contatti il supporto.
- Controlla gli input prima di inviarli. Assicurati che le immagini e i modelli soddisfino i requisiti di formato dell'endpoint.
- Chiama l'API dal tuo server. Il codice eseguito in un browser espone la tua chiave API a chiunque apra la pagina.