Errors

Sa gabay na ito, pag-uusapan natin kung ano ang nangyayari kapag may nagkamali habang ginagamit mo ang Meshy API.

Mga Error sa Request

Ang mga error na ito ay ibinabalik agad kapag na-reject ang iyong API request. Suriin ang HTTP status code at ang message field para maunawaan kung ano ang nangyaring mali.

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

Mga Error sa Gawain

Ang mga error na ito ay nangyayari pagkatapos malikha ang isang gawain at ito ay pinoproseso. Suriin ang task_error na object sa tugon ng gawain para sa mga detalye ng error.

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

Mga Uri ng Error

Ang field na type ay nagsasabi sa iyo ng pangkalahatang kategorya ng kabiguan. Gamitin ito upang magpasya sa iyong retry strategy.

Mga Code ng Error

Kapag ang code na field ay naroroon, ito ay tumutukoy sa isang tiyak at maaring aksyunan na problema. Nasa ibaba ang buong sanggunian para sa bawat code ng error.

image_too_complex

Ang error na ito ay nangyayari kapag ang input na imahe o prompt ay naglalarawan ng isang paksa na masyadong kumplikado sa heometriya para sa 3D generation model na iproseso.

Karaniwang halimbawa ay kinabibilangan ng:

• Siksik na tambak ng maliliit na bagay (hal., isang kahon na puno ng prutas, isang tambak ng mga libro)
• Masalimuot na mga umuulit na pattern (hal., mga istrukturang lattice, scaffolding, wire meshes)
• Kumplikadong mga istruktura ng gusali (hal., mga gusaling may maraming palapag na may maraming bintana at balkonahe)
• Maraming magkakaibang bagay sa isang imahe sa halip na isang solong paksa

Mga halimbawa ng mga input na malamang na masyadong kumplikado:

Resolusyon:

1. Gumamit ng isang solong bagay kada imahe. Ang modelo ay pinakamahusay na gumagana sa isang malinaw na paksa. Huwag isama ang maraming magkakahiwalay na bagay sa parehong imahe o prompt.
2. Pinasimple ang iyong paksa. Bawasan ang antas ng detalye. Halimbawa, isang simpleng plorera sa halip na isang plorera na puno ng dose-dosenang mga bulaklak.
3. Iwasan ang mga prompt na antas-scene. Ang buong mga gusali, mga bloke ng lungsod, mga interior na puno ng kasangkapan, o mga tanawin ay malamang na lumampas sa kapasidad ng modelo. Magtuon sa isang solong bagay sa halip.
4. Iwasan ang siksik na umuulit na mga istruktura. Ang mga paksa tulad ng scaffolding, wire meshes, mga pattern ng lattice, o mga tambak ng maraming maliliit na bagay ay karaniwang mga trigger.

model_missing_uv

Nangyayari ang error na ito kapag nag-upload ka ng modelo para sa texturing na may nakatakdang enable_original_uv sa true, ngunit ang modelo ay walang UV coordinates. Ang UV coordinates ay nagtatakda kung paano ang isang 2D texture ay bumabalot sa 3D na ibabaw ng iyong modelo.

Resolusyon:

Ang tamang solusyon ay nakadepende kung bakit mo itinakda ang enable_original_uv sa true:

• Kung kailangan mong panatilihin ang orihinal na UV layout ng iyong modelo (halimbawa, custom seam placement para sa tumpak na texture mapping): ang iyong modelo ay dapat may wastong UV coordinates. Siguraduhing may UVs sa UV editor ng iyong 3D software bago mag-upload. Tandaan na ang STL files ay hindi makakapag-imbak ng UV data, kaya gamitin ang GLB, FBX, o OBJ sa halip.
• Kung hindi mo kailangan ng partikular na UV control (o hindi ka sigurado): huwag isama ang enable_original_uv o itakda ito sa false. Ang sistema ay awtomatikong lilikha ng UV layout para sa iyong modelo. Ang awtomatikong nalikhang UVs ay na-optimize para sa coverage ngunit wala kang kontrol kung saan ilalagay ang texture seams.

model_insufficient_uv

Nangyayari ang error na ito kapag ang isang modelo ay may UV coordinates, ngunit ang UV coverage ay masyadong maliit para sa kalidad ng pagte-texture. Karaniwang nangyayari ito sa mga modelong na-export mula sa mga 3D tool na bumubuo ng placeholder o collapsed UVs nang walang tamang unwrap.

Resolusyon:

• Kung kailangan mong panatilihin ang iyong orihinal na UV layout: i-re-unwrap ang UVs ng modelo sa iyong 3D software. Siguraduhing ang mga UV island ay maayos na nakakalat sa UV space sa halip na nakatipon sa isang maliit na lugar.
• Kung hindi mo kailangan ng partikular na UV control: huwag isama ang enable_original_uv o itakda ito sa false. Awtomatikong bubuo ang sistema ng bagong UV layout. Ang kapalit nito ay mawawala ang orihinal na seam placement, ngunit ang awtomatikong nabuo na UVs ay magkakaroon ng tamang coverage para sa pagte-texture.

model_missing_texture

Ang error na ito ay nangyayari kapag ang input model ng isang Multi-Color Print task ay walang color information na maaaring paghiwalayin ng converter sa mga print color. Ang isang multi-color 3MF ay binubuo mula sa mga kulay ng model, kaya ang isang plain white mesh — halimbawa isang Text to 3D o Image to 3D preview na hindi kailanman na-texture, o isang repaired / auto-split output — ay walang mapagkukunan.

Ang itinuturing na color source ay depende sa style na hiniling mo:

• Ang realistic ay nagsa-sample ng base color texture sa pamamagitan ng UVs ng model, kaya nangangailangan ito ng iisang base color texture na may UV coordinates sa bawat mesh part.
• Ang cartoon ay nagpapapantay (flatten) ng mga kulay kada face at tumatanggap ng base color texture sa anumang part o per-vertex colors (COLOR_0).

Ang isang model na walang base color texture at walang vertex colors ay tinatanggihan para sa parehong style; sa cartoon, kung hindi man ay "magtatagumpay" ito bilang single-color print.

Karamihan sa mga request ay tinatanggihan bago pa magawa ang task (400 Bad Request na may parehong paliwanag), kaya karaniwang makikita mo lang ang code na ito kapag hindi agad nasuri ang input — isang .fbx upload, halimbawa, ay sinusuri sa sandaling na-normalize na ito ng task.

Resolusyon:

• I-texture muna ang model. Magpatakbo ng Retexture task dito, o buuin ito nang naka-enable ang texturing (isang Text to 3D refine task, o isang Image to 3D task na may should_texture: true), at ipasa ang task na iyon bilang input_task_id.
• Mga vertex-colored na model (photogrammetry scans, hand-painted meshes): humiling ng style: "cartoon", na nagbabasa ng COLOR_0.
• Bahagyang na-texture o multi-texture na mga model sa ilalim ng realistic: bawat mesh part ay nangangailangan ng UVs at ng parehong, iisang base color texture. I-texture ang natitirang mga part o pagsamahin ang mga texture sa iisang atlas, o lumipat sa style: "cartoon".

invalid_input

Ito ang fallback error code kapag ang input ay nabigo sa validation ngunit walang mas tiyak na code na naaangkop. Ang message field ay naglalaman ng tiyak na dahilan para sa pagkabigo.

Karaniwang mga sanhi ay kinabibilangan ng:

• Walang laman o sira na mga model file
• Hindi suportadong mga pagkakaiba-iba ng file format (hal., ASCII FBX files, meshopt-compressed GLB)
• Walang wastong 3D na mga bagay na natagpuan sa na-upload na modelo (hal., ang file ay naglalaman lamang ng armatures, cameras, o lights)
• Nilalaman na hindi pumasa sa mga safety filter

Resolution: Suriin ang message field para sa mga detalye kung ano ang nagkamali. Tiyakin na ang iyong mga input file at mga parameter ay tumutugma sa mga kinakailangan ng endpoint.

moderation_blocked

Ang error na ito ay nangyayari kapag ang iyong prompt o reference images ay tinanggihan ng mga AI safety filter. Sinusuri ng filter ang text prompt at anumang reference images nang sabay-sabay.

Resolusyon:

• I-rephrase ang iyong text prompt upang alisin ang mga suggestive o sensitibong paglalarawan.
• Ayusin ang mga reference image kung naglalaman ang mga ito ng content na maaaring mag-trigger ng mga safety filter.

moderation_unavailable

Ang error na ito ay nangyayari kapag pansamantalang hindi available ang content moderation, kaya naging FAILED ang task sa halip na patakbuhin ito nang walang check. Walang mali sa iyong content. Ang type nito ay server_error.

Resolusyon: Likhain muli ang task.

timeout

Ang error na ito ay nangangahulugang lumampas ang task sa time limit sa server, para sa pagproseso o sa paghihintay sa queue, kaya nabigo ang task at na-refund ang mga credits nito. Maaari itong mangyari dahil sa mataas na load ng sistema o dahil masyadong komplikado ang input para maproseso sa loob ng time limit.

Iba ito sa timeout sa sarili mong code. Kung huminto na ang iyong client sa paghihintay, tumatakbo pa rin ang task; tingnan ang Task Lifecycle.

Resolusyon:

1. Gawin muli ang task. Madalas pansamantala lamang ang mga timeout at maaaring magtagumpay ang bagong task.
2. Pasimplehin ang iyong input. Kung patuloy na nabibigo ang mga pagsubok, maaaring masyadong komplikado ang iyong input. Subukang bawasan ang antas ng detalye sa iyong imahe o prompt. Tingnan ang image_too_complex para sa gabay kung anong mga uri ng input ang mas mahirap iproseso.

queue_timeout

Ang error na ito ay nangangahulugan na masyadong matagal naghintay ang task sa queue nang hindi nagsisimula, kaya nabigo ito at ibinalik ang anumang credits na sinisingil para rito. Hindi ito dulot ng iyong input. Ang type nito ay timeout.

Resolusyon: Gawin muli ang task.

format_conversion_failed

Nagaganap ang error na ito kapag hindi na-convert ang nabuong 3D model sa hiniling mong output format. Matagumpay na nabuo ang model, ngunit nabigo ang hakbang ng conversion.

Resolusyon:

1. Ulitin ang request.
2. Subukan ang ibang output format. Kung paulit-ulit na nabibigo ang isang partikular na format, lumipat sa ibang format na angkop sa iyong pangangailangan.

Pinakamahuhusay na Gawi

1. Magpatupad ng retry logic. Kapag nabigo ang isang task dahil sa timeout, service_unavailable, o server_error na error, likhain ito muli gamit ang exponential backoff. Kung ang sarili mong request ang na-timeout, huwag lumikha ng bagong task: suriin muna ang umiiral na isa (tingnan ang Task Lifecycle).
2. I-log ang mga task ID. Laging i-log ang task ID para sa layuning pag-debug. Isama ito kapag nakikipag-ugnayan sa suporta.
3. I-validate ang mga input. Tiyaking natutugunan ng iyong mga input na larawan at modelo ang mga kinakailangang format bago isumite.
4. Tawagin ang API mula sa iyong server. Ang code na tumatakbo sa isang browser ay maglalantad ng iyong API key sa kahit sinong magbukas ng pahina.