错误

genkiln 的错误格式、所有 HTTP 错误码、任务错误码，以及哪些错误可以安全重试。

错误使用标准 HTTP 状态码，响应体为 JSON，包含稳定、可供程序判断的 code：

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "input.duration: Invalid input",
    "param": "input.duration",
    "request_id": "req_01JC8ZW4H7J2K5M8N1P3Q6R9TV"
  }
}

字段	说明
`code`	下表中的稳定错误码。请根据它做判断，而不是 `message`。
`message`	面向人的说明（英文），措辞可能调整。
`param`	仅出现在部分 `invalid_request` 和 `not_found` 错误中：导致错误的字段，例如 `input.image_urls.0`。
`task`	仅在任务已创建但无法启动时出现：已失败并退款的任务。见创建任务。
`request_id`	本次请求的 ID。所有响应（无论成功与否）都会通过 `X-Request-Id` 响应头返回。

联系支持时请附上 request_id。

HTTP 错误码

HTTP	错误码	含义	可重试？
400	`invalid_request`	请求格式错误或校验失败：JSON 无效、请求体超过 64 KB、未知字段、`input` 不合法、URL 不安全、`metadata` 过大、`cursor` 或 `status` 无效。	否，请修正请求。
401	`invalid_api_key`	API Key 缺失、格式错误、已删除或已过期。	否。
402	`insufficient_credits`	余额低于任务费用，未创建任务。	充值后。
403	`account_suspended`	该 API Key 所属账号已被停用，未创建任务。	否，请联系客服。
403	`content_rejected`	提示词或输入素材被内容安全策略拒绝。	否，请修改提示词或素材。
404	`not_found`	模型或任务不存在，或任务属于其他账号。	否。
409	`idempotency_conflict`	该 `Idempotency-Key` 已用于不同的请求体。	否，请换新 Key 或使用原请求体。
422	`model_unavailable`	模型暂时不可用。	稍后。
429	`rate_limited`	请求过多，或同时进行的任务过多。	是，等待 `Retry-After` 秒。
500	`internal_error`	我们这边出现问题。	是，使用退避重试。
503	`service_busy`	暂时无法启动任务，已扣积分已退还。	是，等待 `Retry-After` 秒。

429 和 503 响应带有 Retry-After 响应头，值为需要等待的秒数。

任务错误码

任务被受理后才失败的，原因写在任务自身的 error 对象中，而不是 HTTP 错误。见查询任务。

`error.code`	含义
`generation_failed`	生成失败。
`content_rejected`	提示词或输入素材被内容安全策略拒绝。
`invalid_input`	输入无法处理，例如图片 URL 无法下载。
`timeout`	任务未在时限内完成。
`service_busy`	服务暂时繁忙。
`canceled`	任务被取消。

以上情况均自动退款。

安全重试

只重试 429、500、503，以及没有收到响应的网络错误。
使用带随机抖动的指数退避，并遵守 Retry-After。
POST /v1/tasks 请始终带上 Idempotency-Key，这样响应丢失后的重试会返回第一个任务，而不会重复扣费。

HTTP 错误码#

任务错误码#

安全重试#

HTTP 错误码

任务错误码

安全重试