Fouten

In deze gids bespreken we wat er gebeurt als er iets misgaat terwijl je met de Meshy API werkt.

Fouten bij verzoeken

Deze fouten worden onmiddellijk geretourneerd wanneer uw API-verzoek wordt afgewezen. Controleer de HTTP-statuscode en het message-veld om te begrijpen wat er fout is gegaan.

{
  "message": "Invalid model file extension: .3dm"
}

Taakfouten

Deze fouten treden op nadat een taak is aangemaakt en wordt verwerkt. Controleer het task_error object in de taakrespons voor foutdetails.

{
  "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"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

Foutsoorten

Het veld type geeft de algemene categorie van de fout aan. Gebruik dit veld om je retry-strategie te bepalen.

Foutcodes

Wanneer het veld code aanwezig is, identificeert het een specifiek, uitvoerbaar probleem. Hieronder is de volledige referentie voor elke foutcode.

image_too_complex

Deze fout treedt op wanneer de invoerafbeelding of prompt een onderwerp beschrijft dat te geometrisch complex is voor het 3D-generatiemodel om te verwerken.

Veelvoorkomende voorbeelden zijn:

• Dichte stapels van kleine objecten (bijv. een krat vol fruit, een stapel boeken)
• Ingewikkelde herhalende patronen (bijv. roosterstructuren, steigers, draadnetten)
• Complexe gebouwstructuren (bijv. gebouwen met meerdere verdiepingen met veel ramen en balkons)
• Meerdere verschillende objecten in één afbeelding in plaats van een enkel onderwerp

Voorbeelden van invoer die waarschijnlijk te complex zijn:

Oplossing:

1. Gebruik één object per afbeelding. Het model werkt het beste met één duidelijk onderwerp. Voeg geen meerdere afzonderlijke objecten toe in dezelfde afbeelding of prompt.
2. Vereenvoudig je onderwerp. Verminder het detailniveau. Bijvoorbeeld, een eenvoudige vaas in plaats van een vaas gevuld met tientallen bloemen.
3. Vermijd scène-niveau prompts. Hele gebouwen, stadsblokken, interieurs gevuld met meubels of landschappen overschrijden waarschijnlijk de capaciteit van het model. Richt je in plaats daarvan op een enkel object.
4. Vermijd dichte herhalende structuren. Onderwerpen zoals steigers, draadnetten, roosterpatronen of stapels van veel kleine items zijn veelvoorkomende triggers.

model_missing_uv

Deze fout treedt op wanneer je een model uploadt voor texturering met enable_original_uv ingesteld op true, maar het model geen UV-coördinaten heeft. UV-coördinaten bepalen hoe een 2D textuur op het 3D-oppervlak van je model wordt gewikkeld.

Oplossing:

De juiste oplossing hangt af van waarom je enable_original_uv op true hebt gezet:

• Als je de originele UV-layout van je model moet behouden (bijv. aangepaste naadplaatsing voor nauwkeurige textuurmapping): je model moet geldige UV-coördinaten hebben. Controleer of UV's bestaan in de UV-editor van je 3D-software voordat je uploadt. Let op dat STL-bestanden geen UV-gegevens kunnen opslaan, dus gebruik in plaats daarvan GLB, FBX of OBJ.
• Als je geen specifieke UV-controle nodig hebt (of je bent niet zeker): laat enable_original_uv weg of stel het in op false. Het systeem genereert automatisch een UV-layout voor je model. De automatisch gegenereerde UV's zijn geoptimaliseerd voor dekking, maar je hebt geen controle over waar textuurnaden worden geplaatst.

model_insufficient_uv

Deze fout treedt op wanneer een model UV-coördinaten heeft, maar de UV-dekking te klein is voor kwalitatieve texturering. Dit gebeurt vaak met modellen die zijn geëxporteerd vanuit 3D-tools die tijdelijke of samengevouwen UV's genereren zonder een juiste unwrap.

Oplossing:

• Als je je originele UV-layout moet behouden: unwrap de UV's van het model opnieuw in je 3D-software. Zorg ervoor dat UV-eilanden goed verspreid zijn over de UV-ruimte in plaats van samengevouwen in een klein gebied.
• Als je geen specifieke UV-controle nodig hebt: laat enable_original_uv weg of stel het in op false. Het systeem genereert automatisch een nieuwe UV-layout. Het nadeel is dat je de originele naadplaatsing verliest, maar de automatisch gegenereerde UV's zullen een goede dekking hebben voor texturering.

model_missing_texture

Deze fout treedt op wanneer het invoermodel van een Multi-Color Print-taak geen kleurinformatie bevat die de converter kan scheiden in printkleuren. Een meerkleuren-3MF wordt opgebouwd uit de kleuren van het model, dus een geheel witte mesh — bijvoorbeeld een Tekst naar 3D- of Afbeelding naar 3D-preview die nooit is getextureerd, of een gerepareerde/automatisch opgesplitste output — biedt niets om mee te werken.

Wat als kleurbron telt, hangt af van de style die je hebt opgegeven:

• realistic bemonstert de basiskleurtextuur via de UV's van het model, dus dit vereist één enkele basiskleurtextuur met UV-coördinaten op elk meshonderdeel.
• cartoon vlakt kleuren per zijvlak af en accepteert een basiskleurtextuur op willekeurig welk onderdeel of per-vertex-kleuren (COLOR_0).

Een model zonder basiskleurtextuur én zonder vertex-kleuren wordt voor beide stijlen geweigerd; bij cartoon zou het anders "slagen" als een eenkleurenprint.

De meeste verzoeken worden al geweigerd voordat de taak wordt aangemaakt (400 Bad Request met dezelfde uitleg), dus je zult deze code meestal alleen zien wanneer de invoer niet vooraf kon worden geïnspecteerd — een .fbx-upload bijvoorbeeld wordt pas gecontroleerd nadat de taak deze heeft genormaliseerd.

Oplossing:

• Textureer het model eerst. Voer een Hertextureren-taak erop uit, of genereer het met texturering ingeschakeld (een Tekst naar 3D refine-taak, of een Afbeelding naar 3D-taak met should_texture: true), en geef die taak door als input_task_id.
• Modellen met vertex-kleuren (fotogrammetriescans, handbeschilderde meshes): vraag style: "cartoon" aan, wat COLOR_0 uitleest.
• Gedeeltelijk getextureerde of multi-textuur-modellen onder realistic: elk meshonderdeel heeft UV's nodig en dezelfde, enkele basiskleurtextuur. Textureer de overige onderdelen of voeg de texturen samen tot één atlas, of schakel over naar style: "cartoon".

invalid_input

Dit is de standaard foutcode wanneer de invoer niet door de validatie komt, maar er geen specifiekere code van toepassing is. Het message veld bevat de specifieke reden voor de fout.

Veelvoorkomende oorzaken zijn onder andere:

• Lege of beschadigde modelbestanden
• Niet-ondersteunde bestandsformaatvariaties (bijv. ASCII FBX-bestanden, meshopt-gecomprimeerde GLB)
• Geen geldige 3D-objecten gevonden in het geüploade model (bijv. bestand bevat alleen armaturen, camera's of lichten)
• Inhoud die niet door de veiligheidsfilters komt

Oplossing: Controleer het message veld voor specifieke details over wat er misging. Verifieer of uw invoerbestanden en parameters voldoen aan de vereisten van het endpoint.

moderation_blocked

Deze fout treedt op wanneer je prompt of referentieafbeeldingen worden afgewezen door AI-veiligheidsfilters. Het filter beoordeelt zowel de tekst-prompt als eventuele referentieafbeeldingen samen.

Oplossing:

• Herformuleer je tekst-prompt om suggestieve of gevoelige beschrijvingen te verwijderen.
• Pas referentieafbeeldingen aan als deze inhoud bevatten die veiligheidsfilters kan activeren.

moderation_unavailable

Deze fout treedt op wanneer contentmoderation tijdelijk niet beschikbaar was, waardoor de taak als mislukt werd gemarkeerd in plaats van te worden uitgevoerd zonder de controle. Er is niets mis met je content. Het type is server_error.

Oplossing: Maak de taak opnieuw aan.

timeout

Deze fout betekent dat de taak een serverzijdige tijdslimiet heeft overschreden, voor verwerking of voor wachten in de wachtrij, waardoor de taak is mislukt en de credits zijn terugbetaald. Dit kan gebeuren door een hoge systeembelasting of omdat de invoer te complex is om binnen de tijdslimiet te verwerken.

Dit verschilt van een timeout in uw eigen code. Als uw client gestopt is met wachten, loopt de taak nog steeds; zie Task Lifecycle.

Oplossing:

1. Maak de taak opnieuw aan. Timeouts zijn vaak tijdelijk en een nieuwe taak kan slagen.
2. Vereenvoudig uw invoer. Als nieuwe pogingen steeds mislukken, is uw invoer mogelijk te complex. Probeer het detailniveau in uw afbeelding of prompt te verminderen. Zie image_too_complex voor richtlijnen over welke soorten invoer moeilijker te verwerken zijn.

queue_timeout

Deze fout betekent dat de taak te lang in de wachtrij heeft gewacht zonder te starten, waardoor deze is mislukt en eventuele credits die ervoor in rekening waren gebracht, zijn terugbetaald. Uw invoer heeft dit niet veroorzaakt. Het type is timeout.

Oplossing: Maak de taak opnieuw aan.

format_conversion_failed

Deze fout treedt op wanneer het gegenereerde 3D-model niet kon worden geconverteerd naar het door u gevraagde uitvoerformaat. Het model is succesvol gegenereerd, maar de conversiestap is mislukt.

Oplossing:

1. Probeer het verzoek opnieuw.
2. Probeer een ander uitvoerformaat. Als een specifiek formaat steeds blijft mislukken, schakel dan over naar een ander formaat dat aan uw behoeften voldoet.

Best Practices

1. Implementeer retry-logica. Wanneer een taak mislukt met een timeout-, service_unavailable- of server_error-fout, maak deze dan opnieuw aan met exponentiële back-off. Als in plaats daarvan uw eigen verzoek een time-out had, maak dan geen nieuwe taak aan: controleer eerst de bestaande (zie Task Lifecycle).
2. Log taak-ID's. Log altijd de taak-ID voor debugdoeleinden. Vermeld deze wanneer u contact opneemt met support.
3. Valideer invoer. Zorg ervoor dat uw invoerafbeeldingen en -modellen aan de formaatvereisten voldoen voordat u ze indient.
4. Roep de API aan vanaf uw server. Code die in een browser wordt uitgevoerd, zou uw API-sleutel blootstellen aan iedereen die de pagina opent.