错误码

错误的返回方式

Rodin API 会在两个不同的位置返回失败信息，正确的客户端需要同时检查这两处。

传输层失败通过 HTTP 状态码返回：400 表示请求格式错误，401 表示缺少或无效的鉴权信息，429 表示触发限流。

应用层失败通过响应体返回，而不是 HTTP 状态码。 被拒绝的提交同样返回 HTTP 201，具体原因在 error 中，可读的详细信息在 message 中。只检查 HTTP 状态码的客户端会把被拒绝的请求当成提交成功，进而去轮询一个根本不存在的任务。

{
  "error": "API_INSUFFICIENT_FUNDS",
  "message": "The fund in your wallet is insufficient to perform this operation."
}

错误码	含义
`INVALID_REQUEST`	请求格式错误、缺少参数或取值无效，详见 `message`。
`API_NO_ACTIVE_SUBSCRIPTION`	账户没有有效订阅。
`API_SUBSCRIPTION_PLAN_TOO_LOW`	当前订阅套餐不支持 API 访问。
`API_PARALLELISM_LIMIT_REACHED`	账户正在运行的任务过多，请等待任务完成后重试。
`API_INSUFFICIENT_FUNDS`	账户余额不足以完成本次请求。
`API_OBJECT_NOT_FOUND_ON_IMAGE`	未在输入图片中检测到物体，或图片格式不受支持。
`IMAGE_CONTENT_VIOLATION`	输入图片在您所在地区不被允许，请更换图片。
`IMAGE_LABEL_LENGTH_TOO_LONG`	提交的 `image_label` 数量超过了上传的图片数量。
`NO_SUCH_TASK`	引用的任务不存在或已过期。
`ASSET_NOT_AVAILABLE`	引用的资产当前状态不支持该操作。
`PERMISSION_DENIED`	账户无权执行该操作。
`API_UNKNOWN`	服务端未预期的错误，详见 `message`。

Text-to-3D 的 prompt 会先被渲染成图片再进行生成，因此纯文本请求同样可能返回 IMAGE_CONTENT_VIOLATION。

查询状态可能返回：

错误码	含义
`NO_SUCH_TASK`	subscription key 未匹配到可用任务。

下载结果可能返回：

错误码	含义
`NO_SUCH_TASK`	task UUID 未匹配到该用户拥有的任务。
`INVALID_REQUEST`	该任务没有此用户可下载的文件。

一个常见错误是传错标识：/status 需要 jobs.subscription_key，/download 需要顶层 uuid。两者互换会返回 NO_SUCH_TASK。

限流按接口和账户分别计算，轮询 /status 的额度远高于提交生成任务的额度。官方定价页会公布 Business API 的每分钟请求数，但该数值随订阅 tier 变化且可能调整，请不要把它写死在代码中。

HTTP 429 会带上 Retry-After 响应头，给出需要等待的秒数。请遵循该响应头，不要立即重试；在运行时应以它为准，而不是任何已公布的限额数字。

对 429 和 5xx 响应应使用退避策略重试。但不要重试响应体中的 error：这类拒绝是确定性的，重新提交只会得到相同结果，同时额外占用一次请求配额。