错误处理 | Developer API

了解 Fit It On API 如何报告错误，包括 API 级别故障和异步运行时错误。

了解 API 如何报告错误有助于您快速响应并保持集成弹性。Fit It On API 将错误分为两个不同的阶段：

API 级别错误： 请求在预测 ID 发布之前立即被拒绝。
运行时错误： 请求被接受并返回了预测 ID，但生成在异步处理期间失败。

API 级别错误

API 级别错误是同步发生的。当您向 /v1/run 发出 POST 请求，或向 /v1/status/{id} 发出 GET 请求时，服务器会在开始任何密集的后台工作之前验证请求。

如果验证失败，API 将返回 HTTP 错误状态（例如 400、401），并且 JSON 响应包含一个 error 消息和一个特定的字符串 code。

{
  "error": "Invalid request payload. Expected { model_name, inputs }",
  "code": "BadRequest"
}

标准错误代码

代码	错误	原因	如何修复
400	BadRequest	请求格式无效或模型名称不受支持	检查 JSON 结构，确保 `model_name` 正确，并验证所有必需的 `inputs` 都已提供。
401	UnauthorizedAccess	API 密钥无效或缺失	验证 `Authorization: Bearer YOUR_API_KEY` 标头是否正确且密钥处于活动状态。
402	OutOfCredits	没有剩余的开发者 API 积分	在重试之前，请在 Fit It On 控制面板中充值您的积分。
403	Forbidden	未经授权访问预测	您正在尝试检查由不同开发者密钥创建的预测状态。
404	NotFound	未找到预测	在轮询状态端点时，确认预测 ID 正确。
413	PayloadTooLarge	负载超出限制	确保输入图像小于 25MB 并使用合理的分辨率。
500	InternalServerError	服务器端错误	使用指数退避重试。如果问题仍然存在，请联系支持。

[!TIP] 重试和幂等性 如果您遇到 API 级别错误，一旦问题解决，您可以安全地重试完全相同的负载。由于请求立即被拒绝，因此没有扣除积分，并且重复处理也不是风险。

运行时错误

运行时错误发生在 API 成功接受您的请求并返回预测 ID 之后。

由于生成模型是高度异步的，您将在轮询 /v1/status/{id} 端点时发现这些错误。如果后台作业失败，该端点将返回 HTTP 200 OK（因为轮询请求本身是成功的），但负载中的 status 字段将为 "failed"。

响应将包含预测 ID 和一个 error 对象，详细说明出了什么问题，包括一个分类的 name 和一个描述性的 message。

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "failed",
  "output": null,
  "error": {
    "name": "ImageLoadError",
    "message": "Failed to load input image: URL returned 404"
  },
  "created_at": "2024-05-15T12:00:00Z",
  "updated_at": "2024-05-15T12:00:10Z"
}

常见运行时错误

大多数运行时问题属于我们模型中的少数几个共享类别：

类别	典型错误消息	如何修复
图像加载错误	`无法获取图像`, `无效图像 URL`	确保提供的 URL 可以公开访问且无需身份验证。对于 Base64，请确保它包含正确的 MIME 类型前缀。
输入验证	`图像分辨率太小`, `缺少必需参数`	确保您的输入资产符合特定模型的最小尺寸和要求。
内容审核	`检测到 NSFW 内容`, `触发安全阻止`	替换或调整输入图像或文本提示以符合安全过滤器。
管道错误	`生成失败`, `服务器错误`	GPU 集群中发生意外故障。使用指数退避重试请求。

[!NOTE] 失败时的积分退款 失败的预测不消耗积分。如果生成在运行时失败（例如，由于 Image Load Error 或 Pipeline Error），在请求开始时扣除的积分将自动退还到您的开发者余额中。

特定端点错误

某些模型在生成过程中具有严格的、特定于工作流的验证规则：

姿态控制： 如果目标图像中未检测到人体，则会失败。
虚拟试穿： 如果无法在服装图像中检测到有效服装，则会失败。
模型生成： 如果提供的面部参考图像不包含清晰、无遮挡的面部，则会失败。

如果您在将输入与文档对齐后仍然看到运行时故障，请提供您的预测 ID 联系支持，以便我们进行调查。