Erreurs
Découvrez pourquoi une requête ou une tâche a échoué, et ce qu'il convient de faire ensuite. Une requête peut échouer immédiatement avec une erreur HTTP, et une tâche peut échouer plus tard avec une task_error.
Erreurs de requête
Meshy renvoie ces erreurs immédiatement, lorsqu'il rejette une requête. Pour savoir ce qui n'a pas fonctionné, vérifiez le code de statut HTTP et le champ message.
Format de la réponse
La réponse d'erreur contient un champ message qui décrit ce qui n'a pas fonctionné :
- Name
- message
- Type
- string
- Description
Une courte description de l'erreur.
Codes de statut
- Name
2xx- Description
Succès.
- Name
200 - OK- Description
La requête a fonctionné.
- Name
202 - Accepted- Description
Meshy a accepté la requête, et le traitement n'est pas encore terminé. Par exemple, une requête qui crée une tâche renvoie
202.
- Name
4xx- Description
Quelque chose ne va pas avec la requête ou votre compte. Chaque statut indique quoi faire.
- Name
400 - Bad Request- Description
La requête n'est pas valide, souvent parce qu'un paramètre requis est manquant ou qu'un paramètre est mal formé.
- Name
401 - Unauthorized- Description
La clé API est manquante, n'est pas valide, ou ne peut pas accéder à ce point de terminaison. Voir Authentification.
- Name
402 - Payment Required- Description
Le compte de la clé API n'a pas assez de crédits pour la requête. Dans le plan gratuit, la plupart des requêtes qui créent une tâche renvoient aussi
402.
- Name
403 - Forbidden- Description
Vous n'êtes pas autorisé à effectuer cette requête, par exemple pour l'une de ces raisons :
- La requête provenait d'une adresse en dehors de la liste d'autorisation IP de la clé API.
- Le filtrage IP de votre organisation a bloqué les fichiers d'une tâche lors de sa lecture.
- Le point de terminaison n'est pas disponible sur votre plan.
- La modération de contenu a bloqué l'entrée. Certains points de terminaison renvoient
400pour cela à la place ; chaque page de point de terminaison liste ses codes. - La clé API appartient à un membre d'équipe qui n'est plus actif dans l'équipe.
- Le compte est banni.
- Name
404 - Not Found- Description
La ressource n'existe pas. Par exemple, obtenir une tâche avec un ID qui n'existe pas renvoie
404.
- Name
409 - Conflict- Description
La ressource existe, mais son état ne permet pas l'opération. Par exemple, supprimer une tâche
IN_PROGRESSrenvoie409, car Meshy ne peut pas rembourser une tâche qu'un worker a commencée. La tâche continue de s'exécuter. Attendez un statut final (SUCCEEDED,FAILED, ouCANCELED), puis supprimez la tâche.
- Name
422 - Unprocessable Entity- Description
La requête est valide, mais Meshy ne peut pas traiter son entrée. Par exemple, Rigging renvoie
422lorsqu'il ne trouve pas de corps humanoïde dans le modèle.
- Name
429 - Too Many Requests- Description
Vous avez envoyé trop de requêtes, ou trop de vos tâches sont en file d'attente ou en cours d'exécution. Lorsque la réponse contient un en-tête
Retry-After, attendez ce nombre de secondes, puis réessayez. Voir Limites de débit.
- Name
5xx- Description
Quelque chose s'est mal passé du côté de Meshy. Réessayez avec un délai croissant. Si l'erreur persiste, consultez la page de statut et contactez-nous sur Discord.
Example: 400 Bad Request
{
"message": "Invalid model file extension: .3dm"
}
Erreurs de tâche
Une tâche créée par Meshy peut tout de même échouer pendant son exécution. Son status devient FAILED, Meshy rembourse ses crédits, et task_error explique pourquoi.
Le task_error d'une tâche échouée comporte les champs suivants :
- Name
- type
- Type
- string
- Description
La catégorie de l'erreur. Elle est toujours présente sur une tâche échouée. Basez-vous dessus pour décider de retenter ou non. Voir Types d'erreurs.
- Name
- message
- Type
- string
- Description
Une description de l'erreur lisible par un humain. Elle est toujours présente sur une tâche échouée.
- Name
- code
- Type
- string
- Optionnel
- Description
Un problème spécifique et documenté sur lequel vous pouvez agir. Présent lorsque Meshy dispose de plus de détails. Voir Codes d'erreur. Meshy peut ajouter de nouveaux codes, donc gérez un code que vous ne reconnaissez pas en vous basant sur son
type.
- Name
- doc_url
- Type
- string
- Optionnel
- Description
Un lien vers l'entrée du code sur cette page, qui indique quoi faire. Présent lorsque
codeest présent.
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."
}
}
Error types
type est la catégorie générale de l'échec. Utilisez-la pour décider de la marche à suivre.
- Name
invalid_input- Description
Il y a un problème avec l'entrée que vous avez envoyée. Lisez
codeetmessage, corrigez l'entrée, puis créez une nouvelle tâche.
- Name
timeout- Description
La tâche a dépassé une limite de temps côté serveur, que ce soit pour le traitement ou pour l'attente dans la file, et a échoué. Meshy rembourse les crédits correspondants. Il s'agit souvent d'un problème temporaire. Créez à nouveau la tâche, et si l'échec persiste, essayez une entrée plus simple.
- Name
service_unavailable- Description
Le service était temporairement indisponible. Patientez un instant, puis créez à nouveau la tâche.
- Name
server_error- Description
Un problème est survenu du côté de Meshy pendant l'exécution de la tâche. Créez à nouveau la tâche. Si l'échec persiste, contactez le support en indiquant l'ID de la tâche.
Codes d'erreur
Lorsque le champ code est présent, il désigne l'un des problèmes suivants.
image_too_complex
L'image d'entrée ou le prompt décrit un sujet trop complexe géométriquement pour la génération 3D.
Par exemple :
- Des amas denses de petits objets, comme une caisse remplie de fruits ou une pile de livres
- Des motifs répétitifs complexes, comme des treillis, des échafaudages ou des mailles métalliques
- Des bâtiments complexes, comme des immeubles à plusieurs étages avec de nombreuses fenêtres et balcons
- Plusieurs objets distincts dans une même image, au lieu d'un sujet unique
Ces entrées sont probablement trop complexes :




Pour résoudre ce problème, essayez une ou plusieurs des solutions suivantes :
- Utilisez un seul objet par image. Meshy fonctionne mieux avec un seul sujet clairement défini, donc ne placez pas plusieurs objets distincts dans la même image ou le même prompt.
- Simplifiez votre sujet. Par exemple, utilisez un simple vase plutôt qu'un vase rempli de dizaines de fleurs.
- Évitez les scènes. Des bâtiments entiers, des pâtés de maisons, des pièces meublées et des paysages sont probablement trop complexes. Concentrez-vous sur un seul objet.
- Évitez les structures répétitives denses. Les échafaudages, mailles métalliques, treillis et amas de petits objets sont des déclencheurs fréquents.
model_missing_uv
Vous avez envoyé un modèle pour la texturation avec enable_original_uv réglé sur true, mais le modèle ne possède pas de coordonnées UV. Les coordonnées UV définissent la façon dont une texture 2D s'enroule autour de la surface 3D.

Pour corriger cela, procédez de l'une des manières suivantes :
- Pour conserver la propre disposition UV de votre modèle, par exemple pour un placement personnalisé des coutures, ajoutez des UV au modèle dans votre logiciel 3D. Vérifiez-les dans son éditeur UV, puis téléchargez à nouveau le modèle. Les fichiers STL ne peuvent pas stocker d'UV, utilisez donc GLB, FBX ou OBJ.
- Si vous n'avez pas besoin de votre propre disposition, ou si vous n'êtes pas sûr, omettez
enable_original_uvou réglez-le surfalse. Meshy crée alors une disposition UV pour le modèle. Les nouveaux UV couvrent bien le modèle, mais vous ne pouvez pas contrôler l'emplacement des coutures de la texture.
model_insufficient_uv
Le modèle possède des coordonnées UV, mais celles-ci couvrent une portion trop réduite de l'espace UV pour permettre une bonne texture. Cela se produit souvent avec des modèles dont l'exportateur a écrit des UV provisoires ou aplaties, sans déploiement correct.

Pour corriger cela, procédez de l'une des manières suivantes :
- Pour conserver votre propre disposition UV, redéployez les UV du modèle dans votre logiciel 3D. Répartissez les îlots sur l'ensemble de l'espace UV au lieu de les concentrer dans un petit coin de celui-ci.
- Si vous n'avez pas besoin de votre propre disposition, omettez
enable_original_uvou définissez-le surfalse. Meshy crée alors une nouvelle disposition UV. Vous perdez le placement de vos coutures, mais les nouvelles UV couvrent un espace suffisant pour la texture.
model_missing_texture
Le modèle d'entrée d'une tâche Multi-Color Print n'a aucune couleur que Meshy peut répartir en couleurs d'impression. Meshy construit un 3MF multicolore à partir des couleurs du modèle, donc un maillage blanc uni n'a rien à exploiter. Par exemple, un aperçu Texte en 3D ou Image en 3D qui n'a jamais été texturé n'a pas de couleur. Il en va de même pour la sortie de Réparer l'imprimabilité, ou une tâche Auto Split qui n'a pas conservé la texture.
Ce qui compte comme couleur dépend du style demandé :
realisticéchantillonne la texture de couleur de base à travers les UV du modèle. Il nécessite une seule texture de couleur de base, et des UV sur chaque partie du maillage.cartoonaplatit les couleurs par face. Il accepte une texture de couleur de base sur n'importe quelle partie, ou des couleurs par sommet (COLOR_0).
Meshy rejette un modèle qui n'a ni texture de couleur de base ni couleurs de sommets pour les deux styles, plutôt que de laisser cartoon le transformer en impression monochrome.
Meshy refuse la plupart de ces requêtes avant même de créer la tâche, avec un 400 et la même explication. Vous n'obtenez généralement ce code que lorsque Meshy ne peut pas vérifier l'entrée à l'avance. Par exemple, Meshy ne vérifie un envoi .fbx qu'après que la tâche l'a converti.
Pour corriger cela, utilisez l'option qui convient à votre modèle :
- Texturez d'abord le modèle. Exécutez Retexturisation dessus, ou générez-le avec une tâche refine Texte en 3D ou une tâche Image en 3D avec
should_texture: true. Envoyez ensuite cette tâche en tant queinput_task_id. - Pour un modèle avec couleurs de sommets, comme un scan photogrammétrique ou un maillage peint à la main, utilisez
style: "cartoon", qui litCOLOR_0. - Pour un modèle partiellement texturé ou multi-texture avec
realistic, donnez à chaque partie du maillage des UV et la même texture de couleur de base unique. Pour cela, texturez les parties restantes, ou fusionnez les textures en un seul atlas. Vous pouvez aussi basculer versstyle: "cartoon".
textured_split_refused
Une tâche d'Auto Split avec keep_texture: true ne parvient pas à conserver la texture du modèle d'entrée sur les parties. Par exemple, le modèle n'a pas d'UV, ou sa texture ne dispose pas de place pour les nouvelles faces créées par les découpes. Meshy rembourse les crédits.
Pour corriger cela, envoyez à nouveau la requête sans keep_texture, ou avec keep_texture: false. Les parties sont alors renvoyées avec chacune une couleur unie.
invalid_input
L'entrée a échoué à une vérification, et aucun code plus spécifique ne s'applique. message indique la raison.
Par exemple :
- Un fichier de modèle vide ou corrompu
- Une variante non prise en charge d'un format de fichier, comme un fichier FBX en ASCII ou un fichier GLB compressé avec meshopt
- Un modèle téléversé sans objet 3D valide, par exemple un fichier contenant uniquement des armatures, des caméras ou des lumières
- Un contenu qui ne passe pas les filtres de sécurité
Pour corriger cela, lisez message pour connaître le problème précis. Vérifiez que vos fichiers d'entrée et vos paramètres respectent les exigences du point de terminaison.
moderation_blocked
Les filtres de sécurité ont rejeté votre prompt ou vos images de référence. Les filtres vérifient le texte et les images ensemble.
Pour résoudre ce problème, effectuez l'une des actions suivantes, ou les deux :
- Reformulez le prompt pour supprimer les descriptions suggestives ou sensibles.
- Changez les images de référence montrant un contenu que les filtres pourraient bloquer.
moderation_unavailable
Type : server_error. La moderation du contenu était temporairement indisponible, Meshy a donc fait échouer la tâche plutôt que d'ignorer la vérification. Rien n'est en cause dans votre contenu.
Pour résoudre ce problème, créez à nouveau la tâche.
timeout
La tâche a dépassé une limite de temps côté serveur, que ce soit pour le traitement ou pour l'attente dans la file, et Meshy l'a donc fait échouer et a remboursé ses crédits. Une forte charge, ou une entrée trop complexe pour être traitée à temps, peut en être la cause.
Ceci est différent d'un timeout dans votre propre code. Si votre client a cessé d'attendre, la tâche est toujours en cours d'exécution. Voir Combien de temps attendre.
Pour corriger cela, suivez ces étapes :
- Recréez la tâche. Les timeouts sont souvent temporaires, et une nouvelle tâche pourrait réussir.
- Si l'échec persiste, simplifiez votre entrée, par exemple en réduisant le niveau de détail de votre image ou de votre prompt. Pour les entrées plus difficiles à traiter, voir
image_too_complex.
queue_timeout
Type : timeout. La tâche a attendu trop longtemps dans la file d'attente sans démarrer, Meshy l'a donc fait échouer et a remboursé tous les crédits facturés pour celle-ci. Votre saisie n'est pas à l'origine de cette erreur.
Pour résoudre ce problème, recréez la tâche.
format_conversion_failed
Meshy a généré le modèle, mais sa conversion vers le format demandé a échoué.
Pour résoudre ce problème, suivez ces étapes :
- Recréez la tâche.
- Si un format échoue systématiquement, demandez un format différent qui répond à vos besoins.
Bonnes pratiques
- Relancez les tâches échouées. Pour une tâche échouée avec
timeout,service_unavailableouserver_error, créez une nouvelle tâche avec un backoff exponentiel. - Ne créez pas de nouvelle tâche lorsque votre propre requête expire. La première tâche peut encore être en cours d'exécution, vérifiez donc si elle existe avant d'en créer une autre. Consultez Combien de temps attendre.
- Consignez les ID des tâches. Incluez l'ID lorsque vous contactez le support.
- Vérifiez les entrées avant de les envoyer. Assurez-vous que les images et les modèles respectent les exigences de format du point de terminaison.
- Appelez l'API depuis votre serveur. Le code exécuté dans un navigateur expose votre clé API à toute personne qui ouvre la page.