14参考手册

错误码

API 的每个错误都以同一种格式返回。请根据 HTTP 状态码、错误码和 details 字段来编写逻辑，把 message 文本展示给人看。

更新于 2026年10月13日API v1

错误格式

错误是一个 JSON，其中的 error 对象包含三个字段：

code: 稳定的错误码，形如 ERR_…。请据此决定下一步怎么做。
message: 展示给人看的文本。它是英文的，措辞可能会变化：不要用程序去解析它。
details: 详细信息：具体哪里不对、该如何修正。该字段可以为空。

400 · 示例

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "ERR_INVALID_REQUEST",
    "message": "The reference image is no longer available. Upload the file again.",
    "details": {
      "reason": "reference_unavailable",
      "input_index": 0,
      "retryable": false
    }
  }
}

不是有效 JSON 的请求体，以及缺少必填字段的 multipart 上传，会被拒绝，返回 422 和形如 {"detail": […]} 的响应体。不会扣费。请不要把它们与 ERR_INPUT_FETCH_FAILED 混淆：它也返回 422，但采用常规格式。

错误码一览

可以按状态码筛选各行，也可以按关键词查找。429 和 503 响应带有以秒为单位的 Retry-After 请求头。

错误码	HTTP	含义与处理
`ERR_INVALID_REQUEST`	400	请求不能按这种形式执行。请阅读 `error.message` 和 `error.details`，修正请求后重新发送。未扣费。
`ERR_CONTENT_POLICY`	400	保留的错误码。安全规则的拒绝是在请求被接收之后判定的，表现为状态为 `failed`、`failure.code: content_policy` 的任务。
`ERR_API_KEY_INVALID`	401	没有密钥，或密钥无法识别：`details.reason` 为 `api_key_missing` 或 `api_key_invalid`。请检查密钥，见密钥与鉴权。
`ERR_INSUFFICIENT_BALANCE`	402	余额不足，或密钥或账号的月度限额已用尽。见余额。
`ERR_ACCOUNT_DISABLED`	403	密钥正确，但账号已被停用。请联系技术支持。
`ERR_API_SUSPENDED`	403	账号的 API 访问已被暂停。请停止发送并联系技术支持；控制台仍可使用。
`ERR_MODEL_NOT_FOUND`	404	你的账号没有这个模型。列表见 `GET /models`。
`ERR_NOT_FOUND`	404	找不到该任务，或它属于其他账号。请检查 `id`。
`ERR_RATE_LIMIT`	429	请求过于频繁、任务轮询的间隔短于 5 秒、新账号的每日上传限额，或访问错误后的临时限制。请等待 `Retry-After` 秒，见限额。
`ERR_QUOTA_EXCEEDED`	429	进行中的任务过多，或同一个幂等键被同时发送了多次。请稍等，再用相同的标识符重试。
`ERR_INPUT_FETCH_FAILED`	422	在生成和扣费之前，未能下载或校验参考图。只有当 `details.retryable = true` 时才重试，否则请更换参考图。
`ERR_GENERATION_FAILED`	500	生成无法启动或无法完成。已扣金额会自动退回。`details.reason = pricing_unavailable` 表示扣费前无法确认价格：请稍后重试。
`ERR_PROVIDER_UNAVAILABLE`	503	暂时不可用。请等待 `Retry-After`，查看 `details.reason`，并限制重试次数。
`ERR_INTERNAL`	500, 503	内部错误，`500` 或 `503`。`500` 不能说明请求是否已被接收：重试前，请用同一个幂等键检查任务。对于什么也没创建的请求，扣费会自动退回。`503` 会附带 `Retry-After`。

访问错误

这些响应对所有使用密钥的方法都是一样的。不要用同一个密钥重试请求：同一 IP 地址上反复出现的 401 和 403 会导致该地址被暂时限制（详见限额）。如何保管和更换密钥，见密钥与鉴权。

发生了什么	响应	怎么办
请求中没有密钥	`401 ERR_API_KEY_INVALID` `details.reason = api_key_missing`；`message`：“no API key on the request”	在 `Authorization` 或 `X-API-Key`
密钥无法识别	`401 ERR_API_KEY_INVALID` `details.reason = api_key_invalid`；`message`：“API key not recognized”	请确认密钥已完整复制，且没有在控制台中被撤销
账号已被停用	`403 ERR_ACCOUNT_DISABLED` `details.reason = account_disabled`；`message`：“this account is disabled”	停止发送并联系技术支持
API 访问已被暂停	`403 ERR_API_SUSPENDED` `details.reason = api_suspended`；`message`：“API access is paused for this account by its account manager”	停止发送并联系技术支持；控制台仍可使用

请求错误

这些拒绝发生在扣费之前。生成不会开始，也不会产生费用。

发生了什么	响应	怎么办
参考图不可用	`400 ERR_INVALID_REQUEST` `details.reason = reference_unavailable`, `details.input_index` 是参考图的位置（从 0 开始）	重新上传文件并替换 `file_id`。用同一个文件重试没有用
参考图无法下载	`422 ERR_INPUT_FETCH_FAILED` `details.reason = input_fetch_failed`, `details.retryable`	`retryable: true` 时请稍后重试，否则请更换参考图
参考图格式不支持	`400 ERR_INVALID_REQUEST` “Unsupported image format. Supported formats: PNG, JPEG, WebP.”	请另存为 PNG、JPEG 或 WebP，见参考图
提示词为空	`400 ERR_INVALID_REQUEST` `details.fields: ["prompt"]`	请传入提示词，即使已有参考图
请求中带有蒙版	`400 ERR_INVALID_REQUEST` 在 `details.fields` 中：`mask` 或 `mask_file_id`	不支持蒙版。请把原图作为参考图传入，并在提示词中说明要做的编辑
分辨率或宽高比不可用	`400 ERR_INVALID_REQUEST` `details.supported` 是可用值的列表	请从列表中选择，见模型与参数
账号没有这种组合	`400 ERR_INVALID_REQUEST` `details.reason = provider_policy_no_route`	请更换分辨率或宽高比，或联系技术支持

暂时性拒绝

503 表示现在无法接收该请求。请查看 details.reason：

`details.reason`	含义	扣费
`overloaded`	服务过载，请求被拒绝。请稍后重试	未扣费
`no_provider_enabled`	所请求的配置目前对该账号不可用。请稍候；如果反复被拒绝，请联系技术支持	未扣费
`provider_unavailable`	无法启动生成	如已扣费，金额会自动退回

有时会返回 details 为空的 503 ERR_INTERNAL：某个依赖的服务暂时不可用。仅凭 5xx 无法判断请求是否已被接收：请用幂等键核对任务。

等待与重试

429 和 503 响应带有以秒为单位的 Retry-After。等待时间不能短于它；轮询任务时，不能短于 Retry-After 与 details.min_interval_seconds 中较大的那个。
重试次数要有限，并加入少量随机延迟，避免各进程同时发起请求。
400、401、402、403、404 不要原样重试：先排除原因。
如果响应丢失、请求返回了 500 或超时，不要创建新任务：请用同一个幂等键重试同一个请求（重试不重复扣费）。

生成是预先付费的，失败时金额会自动退回。错误本身并不确认退款：金额可在“余额”页面和控制台的交易记录中查看。

任务被接收之后的错误

如果请求已被接收（202）但图片没有生成出来，这不是 HTTP 错误。GET /creations/{id} 会返回 200，状态为 failed，并带有 error 字符串。金额会自动退回余额。

error 字段的文本（英文）

"The image or prompt was rejected by the safety filter. Try a different image or rephrase the prompt."
"The source image was rejected. Try a different photo."
"Generation failed. Please try again."
"Nothing was rendered for this request. Describe the image you want in the prompt, or attach the source photo it refers to."
"Generation timed out."
"The reference image is no longer available. Upload the file again."
"Could not download the reference image. Please try again later."
"The service is temporarily unavailable. Please try again later."
"Generation failed."

安全规则拒绝：请调整提示词或换一张图片。
“Nothing was rendered…”：请在提示词中写明所需的图片，或附上它所指的参考图。
“The reference image is no longer available…”：请重新上传文件并替换 file_id。
超时、暂时不可用、一般故障：有限次重试。如果故障持续出现，请把任务的 id 发给技术支持。

如果在 failed 之后想有意生成一张新图片，请使用新的幂等键：原来的键不会重新启动任务，用它重试只会返回已保存的 202 响应，id 与之前相同。新的尝试照常付费，失败时同样退款。

面向程序的失败原因

自 2026年9月24日起，失败的任务还会包含 failure 对象：出现在 GET /creations/{id} 以及 creation.failed Webhook 中。它只在 status: "failed" 时存在，因此解析时请将其视为可选。

200 · 失败的任务

{
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "failed",
  "error": "The image or prompt was rejected by the safety filter. Try a different image or rephrase the prompt.",
  "failure": {
    "type": "declined",
    "code": "content_policy",
    "retryable": false
  }
}

declined: 原因在请求本身：提示词、参考图或输入数据。同样的请求会得到同样的结果：请调整它。
error: 原因在服务一侧。只要 retryable 不等于 false。

`declined` 类型
错误码	含义与处理	重试
`content_policy`	安全规则拒绝了提示词或参考图。请调整提示词或换一张图片	否
`source_image_rejected`	参考图被拒绝。请换一张图片	否
`no_image_output`	模型回复的是文字而不是图片，例如用文字说明了图片的样子，或提示词引用了未附上的图片。请写明所需的图像，或附上图片	否
`reference_unavailable`	参考图已不可用。请重新上传并替换 `file_id`	否
`invalid_request`	请求不能按这种形式执行，例如模型无法生成所选的宽高比。请修正请求	否

`error` 类型
错误码	含义与处理	重试
`timeout`	生成超时。请重试	是
`unavailable`	服务曾暂时不可用。请稍后重试	是
`reference_fetch_failed`	无法下载参考图。请稍后重试	是
`internal`	服务端的其他故障。请稍后重试	是

请依据 failure.type 和 failure.code 编写逻辑，而不是依据 error 的文本：它只用于展示，措辞可能会变。目前的错误码列表是固定的，但以后可能会新增：遇到不认识的错误码时，请按其 failure.type 处理。

失败的请求不收费：金额会立即退回余额。

这适用于两种类型：declined 和 error。

常见问题

哪些错误是最终的，哪些应该重试？

值得重试的是 429、503 和 500（500 要小心，并使用同一个幂等键），以及 failure.retryable 不等于 false 的任务。除 429 以外的 4xx，请先修正。

收到错误后，已扣的金额会退回吗？

会，如果已经扣费：失败的请求不收费，金额会自动退回。错误本身并不确认退款，所以请查看余额和交易记录。

为什么错误文本是英文的？

message 字段和 error 字符串对所有客户端都是一样的，而且可能变化。请用错误码、状态和 failure 来实现逻辑，向用户展示你自己的文本。

错误反复出现怎么办？

请联系技术支持，并附上任务的 id 或请求时间。无需发送 API 密钥和提示词。

14参考手册

错误码

API 的每个错误都以同一种格式返回。请根据 HTTP 状态码、错误码和 details 字段来编写逻辑，把 message 文本展示给人看。

在 ChatGPT 中打开在 Claude 中打开

更新于 2026年10月13日API v1

错误格式

错误是一个 JSON，其中的 error 对象包含三个字段：

code: 稳定的错误码，形如 ERR_…。请据此决定下一步怎么做。
message: 展示给人看的文本。它是英文的，措辞可能会变化：不要用程序去解析它。
details: 详细信息：具体哪里不对、该如何修正。该字段可以为空。

400 · 示例

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "ERR_INVALID_REQUEST",
    "message": "The reference image is no longer available. Upload the file again.",
    "details": {
      "reason": "reference_unavailable",
      "input_index": 0,
      "retryable": false
    }
  }
}

错误码一览

可以按状态码筛选各行，也可以按关键词查找。429 和 503 响应带有以秒为单位的 Retry-After 请求头。

错误码	HTTP	含义与处理
`ERR_INVALID_REQUEST`	400	请求不能按这种形式执行。请阅读 `error.message` 和 `error.details`，修正请求后重新发送。未扣费。
`ERR_CONTENT_POLICY`	400	保留的错误码。安全规则的拒绝是在请求被接收之后判定的，表现为状态为 `failed`、`failure.code: content_policy` 的任务。
`ERR_API_KEY_INVALID`	401	没有密钥，或密钥无法识别：`details.reason` 为 `api_key_missing` 或 `api_key_invalid`。请检查密钥，见密钥与鉴权。
`ERR_INSUFFICIENT_BALANCE`	402	余额不足，或密钥或账号的月度限额已用尽。见余额。
`ERR_ACCOUNT_DISABLED`	403	密钥正确，但账号已被停用。请联系技术支持。
`ERR_API_SUSPENDED`	403	账号的 API 访问已被暂停。请停止发送并联系技术支持；控制台仍可使用。
`ERR_MODEL_NOT_FOUND`	404	你的账号没有这个模型。列表见 `GET /models`。
`ERR_NOT_FOUND`	404	找不到该任务，或它属于其他账号。请检查 `id`。
`ERR_RATE_LIMIT`	429	请求过于频繁、任务轮询的间隔短于 5 秒、新账号的每日上传限额，或访问错误后的临时限制。请等待 `Retry-After` 秒，见限额。
`ERR_QUOTA_EXCEEDED`	429	进行中的任务过多，或同一个幂等键被同时发送了多次。请稍等，再用相同的标识符重试。
`ERR_INPUT_FETCH_FAILED`	422	在生成和扣费之前，未能下载或校验参考图。只有当 `details.retryable = true` 时才重试，否则请更换参考图。
`ERR_GENERATION_FAILED`	500	生成无法启动或无法完成。已扣金额会自动退回。`details.reason = pricing_unavailable` 表示扣费前无法确认价格：请稍后重试。
`ERR_PROVIDER_UNAVAILABLE`	503	暂时不可用。请等待 `Retry-After`，查看 `details.reason`，并限制重试次数。
`ERR_INTERNAL`	500, 503	内部错误，`500` 或 `503`。`500` 不能说明请求是否已被接收：重试前，请用同一个幂等键检查任务。对于什么也没创建的请求，扣费会自动退回。`503` 会附带 `Retry-After`。

访问错误

发生了什么	响应	怎么办
请求中没有密钥	`401 ERR_API_KEY_INVALID` `details.reason = api_key_missing`；`message`：“no API key on the request”	在 `Authorization` 或 `X-API-Key`
密钥无法识别	`401 ERR_API_KEY_INVALID` `details.reason = api_key_invalid`；`message`：“API key not recognized”	请确认密钥已完整复制，且没有在控制台中被撤销
账号已被停用	`403 ERR_ACCOUNT_DISABLED` `details.reason = account_disabled`；`message`：“this account is disabled”	停止发送并联系技术支持
API 访问已被暂停	`403 ERR_API_SUSPENDED` `details.reason = api_suspended`；`message`：“API access is paused for this account by its account manager”	停止发送并联系技术支持；控制台仍可使用

请求错误

这些拒绝发生在扣费之前。生成不会开始，也不会产生费用。

发生了什么	响应	怎么办
参考图不可用	`400 ERR_INVALID_REQUEST` `details.reason = reference_unavailable`, `details.input_index` 是参考图的位置（从 0 开始）	重新上传文件并替换 `file_id`。用同一个文件重试没有用
参考图无法下载	`422 ERR_INPUT_FETCH_FAILED` `details.reason = input_fetch_failed`, `details.retryable`	`retryable: true` 时请稍后重试，否则请更换参考图
参考图格式不支持	`400 ERR_INVALID_REQUEST` “Unsupported image format. Supported formats: PNG, JPEG, WebP.”	请另存为 PNG、JPEG 或 WebP，见参考图
提示词为空	`400 ERR_INVALID_REQUEST` `details.fields: ["prompt"]`	请传入提示词，即使已有参考图
请求中带有蒙版	`400 ERR_INVALID_REQUEST` 在 `details.fields` 中：`mask` 或 `mask_file_id`	不支持蒙版。请把原图作为参考图传入，并在提示词中说明要做的编辑
分辨率或宽高比不可用	`400 ERR_INVALID_REQUEST` `details.supported` 是可用值的列表	请从列表中选择，见模型与参数
账号没有这种组合	`400 ERR_INVALID_REQUEST` `details.reason = provider_policy_no_route`	请更换分辨率或宽高比，或联系技术支持

暂时性拒绝

503 表示现在无法接收该请求。请查看 details.reason：

`details.reason`	含义	扣费
`overloaded`	服务过载，请求被拒绝。请稍后重试	未扣费
`no_provider_enabled`	所请求的配置目前对该账号不可用。请稍候；如果反复被拒绝，请联系技术支持	未扣费
`provider_unavailable`	无法启动生成	如已扣费，金额会自动退回

有时会返回 details 为空的 503 ERR_INTERNAL：某个依赖的服务暂时不可用。仅凭 5xx 无法判断请求是否已被接收：请用幂等键核对任务。

等待与重试

429 和 503 响应带有以秒为单位的 Retry-After。等待时间不能短于它；轮询任务时，不能短于 Retry-After 与 details.min_interval_seconds 中较大的那个。
重试次数要有限，并加入少量随机延迟，避免各进程同时发起请求。
400、401、402、403、404 不要原样重试：先排除原因。
如果响应丢失、请求返回了 500 或超时，不要创建新任务：请用同一个幂等键重试同一个请求（重试不重复扣费）。

生成是预先付费的，失败时金额会自动退回。错误本身并不确认退款：金额可在“余额”页面和控制台的交易记录中查看。

任务被接收之后的错误

error 字段的文本（英文）

"The image or prompt was rejected by the safety filter. Try a different image or rephrase the prompt."
"The source image was rejected. Try a different photo."
"Generation failed. Please try again."
"Nothing was rendered for this request. Describe the image you want in the prompt, or attach the source photo it refers to."
"Generation timed out."
"The reference image is no longer available. Upload the file again."
"Could not download the reference image. Please try again later."
"The service is temporarily unavailable. Please try again later."
"Generation failed."

安全规则拒绝：请调整提示词或换一张图片。
“Nothing was rendered…”：请在提示词中写明所需的图片，或附上它所指的参考图。
“The reference image is no longer available…”：请重新上传文件并替换 file_id。
超时、暂时不可用、一般故障：有限次重试。如果故障持续出现，请把任务的 id 发给技术支持。

面向程序的失败原因

200 · 失败的任务

{
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "failed",
  "error": "The image or prompt was rejected by the safety filter. Try a different image or rephrase the prompt.",
  "failure": {
    "type": "declined",
    "code": "content_policy",
    "retryable": false
  }
}

declined: 原因在请求本身：提示词、参考图或输入数据。同样的请求会得到同样的结果：请调整它。
error: 原因在服务一侧。只要 retryable 不等于 false。

`declined` 类型
错误码	含义与处理	重试
`content_policy`	安全规则拒绝了提示词或参考图。请调整提示词或换一张图片	否
`source_image_rejected`	参考图被拒绝。请换一张图片	否
`no_image_output`	模型回复的是文字而不是图片，例如用文字说明了图片的样子，或提示词引用了未附上的图片。请写明所需的图像，或附上图片	否
`reference_unavailable`	参考图已不可用。请重新上传并替换 `file_id`	否
`invalid_request`	请求不能按这种形式执行，例如模型无法生成所选的宽高比。请修正请求	否

`error` 类型
错误码	含义与处理	重试
`timeout`	生成超时。请重试	是
`unavailable`	服务曾暂时不可用。请稍后重试	是
`reference_fetch_failed`	无法下载参考图。请稍后重试	是
`internal`	服务端的其他故障。请稍后重试	是

失败的请求不收费：金额会立即退回余额。

这适用于两种类型：declined 和 error。

常见问题

哪些错误是最终的，哪些应该重试？

值得重试的是 429、503 和 500（500 要小心，并使用同一个幂等键），以及 failure.retryable 不等于 false 的任务。除 429 以外的 4xx，请先修正。

收到错误后，已扣的金额会退回吗？

会，如果已经扣费：失败的请求不收费，金额会自动退回。错误本身并不确认退款，所以请查看余额和交易记录。

为什么错误文本是英文的？

message 字段和 error 字符串对所有客户端都是一样的，而且可能变化。请用错误码、状态和 failure 来实现逻辑，向用户展示你自己的文本。

错误反复出现怎么办？

请联系技术支持，并附上任务的 id 或请求时间。无需发送 API 密钥和提示词。

01错误格式

02错误码一览

03访问错误

04请求错误

05暂时性拒绝

06等待与重试

07任务被接收之后的错误

08面向程序的失败原因

FAQ常见问题

01错误格式

02错误码一览

03访问错误

04请求错误

05暂时性拒绝

06等待与重试

07任务被接收之后的错误

08面向程序的失败原因

FAQ常见问题

错误格式

错误码一览

访问错误

请求错误

暂时性拒绝

等待与重试

任务被接收之后的错误

面向程序的失败原因

常见问题

错误格式

错误码一览

访问错误

请求错误

暂时性拒绝

等待与重试

任务被接收之后的错误

面向程序的失败原因

常见问题