错误处理

在本指南中，我们将讨论当您使用 Meshy API 时出现问题时会发生什么。

状态码

Meshy 使用常规的 HTTP 响应代码来指示 API 请求的成功或失败。

通常，2xx 范围内的代码表示成功；4xx 范围内的代码表示由于提供的信息导致的错误（例如，缺少必需参数，提供了无效的模型等）；5xx 范围内的代码表示 Meshy 服务器的内部错误，这种情况应该很少见。

但如果您确实看到一个，请查看我们的状态页面以获取更多信息，并通过 Discord 联系我们以获得帮助。

以下是 Meshy API 返回的不同类别状态码的列表。使用这些代码来了解请求是否成功。

  • Name
    2xx
    Description

    2xx 状态码表示响应成功。

    • Name
      200 - OK
      Description

      默认情况下，如果一切按预期工作，将返回 200 状态码。

    • Name
      202 - Accepted
      Description

      您的请求已被接受进行处理，但处理尚未完成。这是来自 Meshy API 的非承诺响应。例如，创建一个新的文本生成纹理任务的请求将返回 202 状态码。

  • Name
    4xx
    Description

    4xx 状态码表示客户端错误——这意味着这是一个 您的 问题。

    • Name
      400 - Bad Request
      Description

      请求不可接受，通常是由于缺少必需参数或某个参数格式错误。

    • Name
      401 - Unauthorized
      Description

      未提供有效的 API 密钥或提供的 API 密钥无权访问 Meshy API 端点。

    • Name
      403 - Forbidden
      Description

      请求的资源禁止访问。如果您尝试直接从客户端 JavaScript 代码访问 Meshy API，可能会发生这种情况，因为不允许浏览器的跨域资源共享 (CORS) 请求。考虑使用服务器端代理进行此类请求。有关更多详细信息，请参阅 MDN CORS 指南。

    • Name
      402 - Payment Required
      Description

      提供的 API 密钥关联的账户资金不足。

    • Name
      404 - Not Found
      Description

      请求的资源不存在。例如，当您尝试通过任务 ID 检索任务但提供了无效的 ID 时，您将获得 404 状态码。

    • Name
      429 - Too Many Requests
      Description

      太多请求过快地击中了 Meshy API。请参阅 速率限制 指南以获取详细信息。

  • Name
    5xx
    Description

    5xx 状态码表示服务器错误，我们希望您不会看到这些——但如果您确实看到，请联系我们以获得帮助！

错误响应

每当请求不成功时，Meshy API 将返回带有错误类型和消息的错误响应。您可以使用此信息更好地了解出了什么问题以及如何解决它。大多数错误消息应该是有帮助和可操作的，它们也共享一个通用结构：

  • Name
    message
    Type
    string
    Description

    错误的简短描述信息。

400示例响应 - 错误请求状态码

{
  "message": "无效的模型文件扩展名: .3dm"
}

任务失败

当任务状态变为 FAILED 时，任务响应中的 task_error 字段将包含有关错误原因的信息。

常见失败原因

task_error.message 中的错误消息出于安全考虑已简化。以下是常见的失败场景：

  • Name
    The server is busy. Please try again later.（服务器繁忙，请稍后重试）
    Description

    此错误发生在以下情况：

    • 超时：任务超出了最大处理时间。
    • 服务器积压：处理服务器暂时过载。

    建议操作：等待几分钟后重试任务。如果问题持续存在，请查看状态页面了解是否有正在进行的事件。

  • Name
    The input file or parameters could not be processed. Please check your input and try again.（输入文件或参数无法处理）
    Description

    此错误在以下情况发生：

    • 无法处理的内容：输入文件或参数在处理过程中未通过验证。

    建议操作：检查您的输入文件是否有效且参数正确，然后重试。

  • Name
    Internal server error.（内部服务器错误）
    Description

    这是一个通用错误，可能由以下原因导致：

    • 模型处理失败：输入的模型或图像无法正确处理。
    • 生成失败：3D 生成流程遇到意外问题。
    • 文件损坏：输入文件或中间文件在处理过程中损坏。

    建议操作：验证您的输入文件是否有效并重试。如果问题持续存在，请通过 Discord 联系支持团队并提供您的任务 ID。

处理任务失败的最佳实践

  1. 实现重试逻辑：对于服务器繁忙或超时等瞬态错误，实现指数退避重试逻辑。
  2. 监控任务状态：轮询任务状态端点以尽早检测失败。
  3. 记录任务 ID：始终记录任务 ID 以便调试。
  4. 验证输入：在提交前确保您的输入图像和模型符合格式要求。

FAILED 状态的任务响应示例

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "message": "The server is busy. Please try again later."
  },
  "created_at": 1692771347514,
  "started_at": 1692771347514,
  "finished_at": 1692771397514
}