Erros

Neste guia, falaremos sobre o que acontece quando algo dá errado enquanto você trabalha com a Meshy API.

Erros de Requisição

Esses erros são retornados imediatamente quando sua requisição de API é rejeitada. Verifique o código de status HTTP e o campo message para entender o que deu errado.

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

Erros de Tarefa

Esses erros ocorrem após uma tarefa ter sido criada e estar em processamento. Verifique o objeto task_error na resposta da tarefa para obter detalhes sobre o erro.

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

Tipos de Erro

O campo type informa a categoria geral da falha. Use-o para decidir sua estratégia de nova tentativa.

Códigos de Erro

Quando o campo code está presente, ele identifica um problema específico e acionável. Abaixo está a referência completa para cada código de erro.

image_too_complex

Este erro ocorre quando a imagem de entrada ou prompt descreve um assunto que é muito geometricamente complexo para o modelo de geração 3D processar.

Exemplos comuns incluem:

• Pilhas densas de pequenos objetos (por exemplo, uma caixa cheia de frutas, uma pilha de livros)
• Padrões repetitivos intrincados (por exemplo, estruturas de treliça, andaimes, malhas de arame)
• Estruturas de edifícios complexas (por exemplo, edifícios de vários andares com muitas janelas e varandas)
• Múltiplos objetos distintos em uma imagem em vez de um único assunto

Exemplos de entradas que provavelmente são muito complexas:

Resolução:

1. Use um único objeto por imagem. O modelo funciona melhor com um assunto claro. Não inclua múltiplos objetos separados na mesma imagem ou prompt.
2. Simplifique seu assunto. Reduza o nível de detalhe. Por exemplo, um vaso simples em vez de um vaso cheio de dezenas de flores.
3. Evite prompts em nível de cena. Edifícios inteiros, quarteirões, interiores cheios de móveis ou paisagens provavelmente excedem a capacidade do modelo. Foque em um único objeto.
4. Evite estruturas repetitivas densas. Assuntos como andaimes, malhas de arame, padrões de treliça ou pilhas de muitos itens pequenos são gatilhos comuns.

model_missing_uv

Este erro ocorre quando você faz o upload de um modelo para texturização com enable_original_uv definido como true, mas o modelo não possui coordenadas UV. As coordenadas UV definem como uma textura 2D se ajusta à superfície 3D do seu modelo.

Resolução:

A correção correta depende do motivo pelo qual você definiu enable_original_uv como true:

• Se você precisa preservar o layout UV original do seu modelo (por exemplo, colocação personalizada de costuras para mapeamento de textura preciso): seu modelo deve ter coordenadas UV válidas. Verifique se as UVs existem no editor UV do seu software 3D antes de fazer o upload. Note que arquivos STL não podem armazenar dados UV, então use GLB, FBX ou OBJ em vez disso.
• Se você não precisa de controle específico sobre UVs (ou não tem certeza): omita enable_original_uv ou defina-o como false. O sistema gerará automaticamente um layout UV para o seu modelo. As UVs geradas automaticamente são otimizadas para cobertura, mas você não terá controle sobre onde as costuras da textura são colocadas.

model_insufficient_uv

Este erro ocorre quando um modelo possui coordenadas UV, mas a cobertura UV é muito pequena para uma texturização de qualidade. Isso geralmente acontece com modelos exportados de ferramentas 3D que geram UVs de espaço reservado ou colapsados sem um desdobramento adequado.

Resolução:

• Se você precisa preservar seu layout UV original: redesenhe as UVs do modelo no seu software 3D. Certifique-se de que as ilhas UV estejam devidamente distribuídas pelo espaço UV em vez de colapsadas em uma área pequena.
• Se você não precisa de controle específico sobre UVs: omita enable_original_uv ou defina como false. O sistema gerará automaticamente um novo layout UV. A desvantagem é que você perde o posicionamento original das costuras, mas as UVs geradas automaticamente terão cobertura adequada para texturização.

model_missing_texture

Este erro ocorre quando o modelo de entrada de uma tarefa de Impressão Multicolorida não possui informação de cor que o conversor consiga separar em cores de impressão. Um 3MF multicolorido é construído a partir das cores do modelo, então uma malha branca simples — por exemplo, uma prévia de Texto para 3D ou Imagem para 3D que nunca foi texturizada, ou uma saída reparada / dividida automaticamente — não tem nada com que trabalhar.

O que conta como fonte de cor depende do style solicitado:

• realistic amostra a textura de cor base através das coordenadas UV do modelo, portanto requer uma única textura de cor base com coordenadas UV em todas as partes da malha.
• cartoon achata as cores por face e aceita uma textura de cor base em qualquer parte ou cores por vértice (COLOR_0).

Um modelo sem textura de cor base nem cores de vértice é rejeitado em ambos os estilos; com cartoon, caso contrário, ele "teria sucesso" como uma impressão de cor única.

A maioria das solicitações é recusada antes que a tarefa seja criada (400 Bad Request com a mesma explicação), então você geralmente verá este código apenas quando a entrada não pôde ser inspecionada antecipadamente — um upload .fbx, por exemplo, é verificado assim que a tarefa o normaliza.

Resolução:

• Texturize o modelo primeiro. Execute uma tarefa de Retexturizar nele, ou o gere com texturização habilitada (uma tarefa de refine de Texto para 3D, ou uma tarefa de Imagem para 3D com should_texture: true), e passe essa tarefa como input_task_id.
• Modelos com cores de vértice (escaneamentos de fotogrametria, malhas pintadas manualmente): solicite style: "cartoon", que lê COLOR_0.
• Modelos parcialmente texturizados ou com múltiplas texturas sob realistic: cada parte da malha precisa de coordenadas UV e da mesma e única textura de cor base. Texturize as partes restantes ou combine as texturas em um único atlas, ou mude para style: "cartoon".

invalid_input

Este é o código de erro padrão quando a validação da entrada falha, mas nenhum código mais específico se aplica. O campo message contém o motivo específico da falha.

Causas comuns incluem:

• Arquivos de modelo vazios ou corrompidos
• Variações de formato de arquivo não suportadas (por exemplo, arquivos FBX ASCII, GLB comprimidos com meshopt)
• Nenhum objeto 3D válido encontrado no modelo enviado (por exemplo, o arquivo contém apenas armaduras, câmeras ou luzes)
• Conteúdo que não passa nos filtros de segurança

Resolução: Verifique o campo message para detalhes sobre o que deu errado. Confirme se seus arquivos de entrada e parâmetros correspondem aos requisitos do endpoint.

moderation_blocked

Este erro ocorre quando seu prompt ou imagens de referência são rejeitados pelos filtros de segurança de IA. O filtro avalia tanto o prompt de texto quanto quaisquer imagens de referência em conjunto.

Resolução:

• Reformule seu prompt de texto para remover descrições sugestivas ou sensíveis.
• Ajuste as imagens de referência se elas retratarem conteúdo que possa acionar os filtros de segurança.

timeout

Este erro significa que o tempo de processamento da sua tarefa excedeu o limite permitido. Isso pode acontecer devido a uma alta carga do sistema ou porque a entrada é muito complexa para ser processada dentro do limite de tempo.

Resolução:

1. Tente novamente a solicitação. Timeouts são frequentemente transitórios e uma nova tentativa pode ser bem-sucedida.
2. Simplifique sua entrada. Se as tentativas continuarem falhando, sua entrada pode ser muito complexa. Tente reduzir o nível de detalhe na sua imagem ou prompt. Veja image_too_complex para orientações sobre quais tipos de entradas são mais difíceis de processar.

format_conversion_failed

Este erro ocorre quando o modelo 3D gerado não pôde ser convertido para o formato de saída solicitado. O modelo foi gerado com sucesso, mas a etapa de conversão falhou.

Resolução:

1. Tente novamente a solicitação.
2. Experimente um formato de saída diferente. Se um formato específico continuar falhando, mude para outro formato que atenda às suas necessidades.

Melhores Práticas

1. Implemente lógica de nova tentativa. Para erros de timeout e service_unavailable, implemente lógica de nova tentativa com recuo exponencial.
2. Registre IDs de tarefas. Sempre registre o ID da tarefa para fins de depuração. Inclua-o ao entrar em contato com o suporte.
3. Valide as entradas. Certifique-se de que suas imagens e modelos de entrada atendam aos requisitos de formato antes do envio.