Fouten

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

Verzoekfouten

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

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

Fouttypen

Het type veld vertelt je de brede categorie van de fout. Gebruik het om je herhalingsstrategie 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. De filter evalueert zowel de tekstprompt als eventuele referentieafbeeldingen samen.

Oplossing:

• Herschrijf je tekstprompt om suggestieve of gevoelige beschrijvingen te verwijderen.
• Pas referentieafbeeldingen aan als ze inhoud weergeven die veiligheidsfilters kunnen activeren.

timeout

Deze fout betekent dat de verwerkingstijd van je taak de toegestane limiet heeft overschreden. Dit kan gebeuren door een hoge systeembelasting of omdat de invoer te complex is om binnen de tijdslimiet te verwerken.

Oplossing:

1. Probeer het verzoek opnieuw. Timeouts zijn vaak tijdelijk en een nieuwe poging kan slagen.
2. Vereenvoudig je invoer. Als herhaalde pogingen blijven mislukken, kan je invoer te complex zijn. Probeer het detailniveau in je afbeelding of prompt te verminderen. Zie image_too_complex voor richtlijnen over welke soorten invoer moeilijker te verwerken zijn.

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 de aanvraag opnieuw.
2. Probeer een ander uitvoerformaat. Als een specifiek formaat blijft falen, schakel dan over naar een ander formaat dat aan uw behoeften voldoet.

Beste Praktijken

1. Implementeer retry-logica. Voor timeout en service_unavailable fouten, implementeer exponentiële backoff retry-logica.
2. Log taak-ID's. Log altijd de taak-ID voor foutopsporingsdoeleinden. Voeg deze toe wanneer u contact opneemt met de ondersteuning.
3. Valideer invoer. Zorg ervoor dat uw invoerafbeeldingen en modellen voldoen aan de formaatvereisten voordat u ze indient.