API 文档 · 可靠性

错误码

统一错误体与全部错误码。

所有错误使用统一结构（见右侧示例）。下表列出接口可能返回的 error.code 及其 HTTP 状态码，同一状态码可能对应多个错误码：

HTTP	code	场景	可重试	建议
400	`invalid_request`	JSON 格式错误、Content-Type 不是 application/json，或缺少 / 超长的 Idempotency-Key；请求体超过 1 MB 时为 413	否	修正请求后重发
401	`invalid_api_key`	Key 不存在、已撤销、已过期或已停用	否	在控制台检查 Key 状态
401	`unauthenticated`	控制台会话未登录或已过期	否	重新登录
402	`quota_exceeded`	账号可用额度不足；冻结上界超过 max_budget（param 为 max_budget）；素材存储空间已满	否	补充额度、调整 max_budget 或清理素材后重试
402	`key_limit_exceeded`	Key 累计或日限额不足	否	调整 Key 限额后重试
403	`permission_denied`	Key 缺少 scope、模型不在 Key 白名单，或账号未开通该模型	否	在控制台为 Key 增加权限，或联系运营开通模型
403	`csrf_failed`	控制台请求缺少或携带了失效的 CSRF 令牌	否	刷新页面后重试
403	`account_suspended`	账号已被停用	否	联系运营
404	`not_found`	资源不存在，或不属于你	否	检查 ID 是否正确
404	`not_available`	仅海外站提供的功能在本站不可用	否	改用对应站点
403	`terms_required`	尚未同意最新的充值须知	否	阅读并同意充值须知后重试
409	`idempotency_conflict`	同一幂等键，但请求体不同	否	为新请求使用新的幂等键
409	`conflict`	资源状态冲突	否	重新查询最新状态后再操作
409	`group_not_empty`	分组内仍有素材	否	先移走或删除分组内素材
422	`invalid_parameter`	参数不合法或组合不受支持（不会静默丢弃）	否	对照能力表修正参数
422	`asset_not_ready`	素材仍在处理中	是	等待状态变为 available 后重试
422	`authorization_required`	真人素材缺少有效授权	否	完成真人授权后重试
429	`rate_limited`	超出 Key 的 RPM，或账号 / Key 的并发上限	是	按 Retry-After 退避后重试
500	`internal_error`	平台内部错误	是	带同一幂等键重试

retryable 为 true 时可退避后重试；创建任务的重试必须带同一个 Idempotency-Key。

受理之后才发生的失败（例如暂时没有可用线路）不会作为接口错误返回，而是体现在任务的 error.code 中，见任务失败码。

错误响应

HTTP/1.1 422 Unprocessable Entity
X-Request-Id: req_xxx

{
  "error": {
    "code": "asset_not_ready",
    "message": "素材 asset_xxx 仍在处理中，请在状态变为 available 后重试",
    "param": "inputs[0].asset_id",
    "retryable": true,
    "request_id": "req_xxx"
  }
}