Errors

In this guide, we will talk about what happens when something goes wrong while you work with the Meshy API.

Request Errors

These errors are returned immediately when your API request is rejected. Check the HTTP status code and message field to understand what went wrong.

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

Task Errors

These errors occur after a task has been created and is processing. Check the task_error object on the task response for error 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"
  }
}

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

Error Types

The type field tells you the broad category of the failure. Use it to decide your retry strategy.

Error Codes

When the code field is present, it identifies a specific, actionable problem. Below is the full reference for each error code.

image_too_complex

This error occurs when the input image or prompt describes a subject that is too geometrically complex for the 3D generation model to process.

Common examples include:

• Dense piles of small objects (e.g., a crate full of fruit, a stack of books)
• Intricate repeating patterns (e.g., lattice structures, scaffolding, wire meshes)
• Complex building structures (e.g., multi-story buildings with many windows and balconies)
• Multiple distinct objects in one image instead of a single subject

Examples of inputs that are likely too complex:

Resolution:

1. Use a single object per image. The model works best with one clear subject. Don't include multiple separate objects in the same image or prompt.
2. Simplify your subject. Reduce the level of detail. For example, a simple vase instead of a vase filled with dozens of flowers.
3. Avoid scene-level prompts. Entire buildings, city blocks, interiors filled with furniture, or landscapes are likely to exceed the model's capacity. Focus on a single object instead.
4. Avoid dense repeating structures. Subjects like scaffolding, wire meshes, lattice patterns, or piles of many small items are common triggers.

model_missing_uv

This error occurs when you upload a model for texturing with enable_original_uv set to true, but the model has no UV coordinates. UV coordinates define how a 2D texture wraps onto the 3D surface of your model.

Resolution:

The right fix depends on why you set enable_original_uv to true:

• If you need to preserve your model's original UV layout (e.g., custom seam placement for precise texture mapping): your model must have valid UV coordinates. Verify UVs exist in your 3D software's UV editor before uploading. Note that STL files cannot store UV data, so use GLB, FBX, or OBJ instead.
• If you don't need specific UV control (or you're not sure): omit enable_original_uv or set it to false. The system will automatically generate a UV layout for your model. The auto-generated UVs are optimized for coverage but you won't have control over where texture seams are placed.

model_insufficient_uv

This error occurs when a model has UV coordinates, but the UV coverage is too small for quality texturing. This commonly happens with models exported from 3D tools that generate placeholder or collapsed UVs without a proper unwrap.

Resolution:

• If you need to preserve your original UV layout: re-unwrap the model's UVs in your 3D software. Ensure UV islands are properly spread across the UV space rather than collapsed into a small area.
• If you don't need specific UV control: omit enable_original_uv or set it to false. The system will automatically generate a new UV layout. The tradeoff is you lose your original seam placement, but the auto-generated UVs will have proper coverage for texturing.

invalid_input

This is the fallback error code when the input fails validation but no more specific code applies. The message field contains the specific reason for the failure.

Common causes include:

• Empty or corrupted model files
• Unsupported file format variations (e.g., ASCII FBX files, meshopt-compressed GLB)
• No valid 3D objects found in the uploaded model (e.g., file contains only armatures, cameras, or lights)
• Content that does not pass safety filters

Resolution: Check the message field for specifics on what went wrong. Verify your input files and parameters match the endpoint's requirements.

moderation_blocked

This error occurs when your prompt or reference images are rejected by AI safety filters. The filter evaluates both the text prompt and any reference images together.

Resolution:

• Rephrase your text prompt to remove suggestive or sensitive descriptions.
• Adjust reference images if they depict content that may trigger safety filters.

timeout

This error means your task's processing time exceeded the allowed limit. This can happen due to high system load or because the input is too complex to process within the time limit.

Resolution:

1. Retry the request. Timeouts are often transient and a retry may succeed.
2. Simplify your input. If retries keep failing, your input may be too complex. Try reducing the level of detail in your image or prompt. See image_too_complex for guidance on what types of inputs are harder to process.

format_conversion_failed

This error occurs when the generated 3D model could not be converted to your requested output format. The model was generated successfully, but the conversion step failed.

Resolution:

1. Retry the request.
2. Try a different output format. If a specific format keeps failing, switch to another format that suits your needs.

Best Practices

1. Implement retry logic. For timeout and service_unavailable errors, implement exponential backoff retry logic.
2. Log task IDs. Always log the task ID for debugging purposes. Include it when contacting support.
3. Validate inputs. Ensure your input images and models meet the format requirements before submission.