Errors

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

Mga Error sa Request

Ang mga error na ito ay ibinabalik kaagad kapag tinanggihan ang iyong API request. Suriin ang HTTP status code at ang message field upang maunawaan kung ano ang nagkamali.

{
  "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 type na field ay nagsasabi sa iyo ng malawak na kategorya ng pagkabigo. 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

Nangyayari ang error na ito kapag ang iyong prompt o reference images ay tinanggihan ng AI safety filters. Sinusuri ng filter ang parehong text prompt at anumang reference images nang magkasama.

Resolution:

• Baguhin ang iyong text prompt upang alisin ang mga mapang-akit o sensitibong paglalarawan.
• Ayusin ang reference images kung naglalaman ito ng nilalaman na maaaring mag-trigger ng safety filters.

timeout

Ibig sabihin ng error na ito ay lumampas ang oras ng pagproseso ng iyong gawain sa pinapayagang limitasyon. Maaaring mangyari ito dahil sa mataas na load ng sistema o dahil masyadong kumplikado ang input para maproseso sa loob ng limitasyon ng oras.

Resolution:

1. Subukang muli ang kahilingan. Ang mga timeout ay madalas na pansamantala at maaaring magtagumpay ang isang pagsubok muli.
2. Pagaanin ang iyong input. Kung patuloy na nabibigo ang mga pagsubok muli, maaaring masyadong kumplikado 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.

format_conversion_failed

Nangyayari ang error na ito kapag ang nabuo na 3D model ay hindi ma-convert sa iyong hiniling na output format. Ang model ay matagumpay na nabuo, ngunit nabigo ang conversion step.

Resolusyon:

1. Subukang muli ang kahilingan.
2. Subukan ang ibang output format. Kung ang isang partikular na format ay patuloy na nabibigo, lumipat sa ibang format na angkop sa iyong pangangailangan.

Pinakamahusay na Kasanayan

1. Ipatupad ang retry logic. Para sa timeout at service_unavailable errors, ipatupad ang exponential backoff retry logic.
2. I-log ang mga task ID. Laging i-log ang task ID para sa debugging purposes. Isama ito kapag nakikipag-ugnayan sa suporta.
3. I-validate ang mga input. Tiyakin na ang iyong mga input na imahe at modelo ay tumutugon sa mga kinakailangan sa format bago isumite.