seedance 资源管理接口错误码指引
面向 API 调用方的 seedance 资源管理错误码指引，按 HTTP 状态码分类。
响应格式约定
管理接口（
/api/model-resources系列）业务错误统一返回 HTTP 200，响应体仅含两个字段：json{ "success": false, "message": "APIkey 对应的分组通道与资源分组不一致，请检查令牌的seedance分组！" }管理接口不返回
code字段，调用方以message的中文提示为准。任务提交与资源引用接口按标准 HTTP 状态码返回错误（OpenAI 兼容格式，含
code字段）。任务提交成功但生成失败时，查询任务返回任务失败状态码（见文末附表）。
HTTP 200 · 业务错误（资源管理接口）
1. 认证与会话
| message | 原因说明 | 解决方案 |
|---|---|---|
| 会话已过期 | 登录态失效或未携带有效凭据调用管理接口 | 重新登录后重试，或改用 API Key 认证 |
| API Key 不属于当前用户 | 请求使用的 API Key 与登录用户不匹配 | 使用当前用户自己的 API Key |
| API Key 不存在或已删除 | 使用的 API Key 已被删除或失效 | 重新生成 API Key 后重试 |
2. 参数校验
| message | 原因说明 | 解决方案 |
|---|---|---|
| 无效的资源分组ID | group_id 非正整数或路由 :id 非法 | 检查并修正 group_id 参数 |
| 无效的资源ID | uuid 参数为空 | 传入有效的资源 UUID（tkres_ 开头） |
| 资源分组名称不能为空 | 创建/更新分组未传 name | 补充 name 字段 |
| 资源分组名称不能超过64个字符 | 分组名称超长 | 缩短至 64 字符以内 |
| 资源分组描述不能超过300个字符 | 分组描述超长 | 缩短至 300 字符以内 |
| 资源名称不能为空 | 创建/更新资源未传 name | 补充 name 字段 |
| 资源名称不能超过128个字符 | 资源名称超长 | 缩短至 128 字符以内 |
| 资源描述不能超过500个字符 | 资源描述超长 | 缩短至 500 字符以内 |
| metadata 不是有效 JSON | metadata 字段格式非法 | 传入合法 JSON 字符串 |
| 无效的 resource_type | 仅支持 image/video/audio/document/archive/other | 检查取值 |
| 无效的 source_type | 仅支持 upload/model_generated/external_import | 检查取值 |
| 无效的 storage_type | 仅支持 local/s3/url/provider | 检查取值 |
| busi_type 仅支持 0(个人资源)、1(机构资源)、2(企业资源) | busi_type 越界 | 使用 0/1/2 |
| group_id 无效 | 更新资源时 group_id 为负 | 使用有效分组 ID |
| 同步供应商资源需要指定 group_id | 创建资源未指定分组 | 先建分组再传入 group_id |
| 同步供应商资源需要提供 url | 创建资源 url 为空 | 提供可访问的资源 URL |
| 机构资源需要指定 organization_id | 机构级资源缺部门归属 | 补充 organization_id 或改个人资源 |
3. 数据不存在
| message | 原因说明 | 解决方案 |
|---|---|---|
| 资源分组不存在 | 分组已删除或不可见 | 确认分组 ID 或通过列表接口查询 |
| 资源不存在 | 资源已删除或不可见 | 确认 UUID 或通过列表接口查询 |
| 部门不存在 | 指定部门不存在 | 检查 organization_id |
4. 权限与归属
| message | 原因说明 | 解决方案 |
|---|---|---|
| 仅资源分组创建人可以维护 | 只有创建人可修改/删除分组 | 使用创建人账号或 API Key |
| 无权维护该资源分组 | 非创建人且不在同一租户 scope | 联系分组所属管理员 |
| 仅资源创建人可以维护 | 只有创建人可修改/删除资源 | 使用创建人账号或 API Key |
| 无权维护该资源 | 非创建人且不在同一租户 scope | 联系资源所属管理员 |
| 资源引用需要使用 API Key 访问 | 未携带 API Key | 改用 API Key 认证调用 |
| API Key 缺少部门成员归属信息 | 部门成员型 Key 缺归属信息 | 重新创建/配置 API Key |
| API Key 缺少企业或部门归属信息 | 企业直连型 Key 缺归属信息 | 重新创建/配置 API Key |
| API Key busi_type 无效 | Key 业务类型非法 | 重新创建 API Key |
| 用户不属于该部门 | 用户不在部门成员列表 | 加入部门或调整请求 scope |
| 无权访问该企业 | 用户无权访问目标企业 | 申请企业访问权限 |
| API Key 未绑定可用分组 | Key 未绑定模型分组 | 在管理后台为 Key 绑定分组 |
| APIkey 对应的分组通道与资源分组不一致，请检查令牌的seedance分组！ | Key 分组下可用渠道的供应商与分组绑定供应商不一致 | 改用绑定同一供应商的 API Key，或将资源放入与 Key 供应商一致的分组 |
5. 供应商与凭据配置
| message | 原因说明 | 解决方案 |
|---|---|---|
| 未配置启用的火山资源供应商 / 分组下无可用火山/豆包视频渠道 / 渠道未配置资源供应商 | 未配置供应商，或 Key 分组下无可用渠道 | 联系管理员配置供应商及 AK/SK |
| 资源供应商配置不存在或未启用 | 供应商配置被停用或不存在 | 联系管理员启用配置 |
| 资源供应商关联的渠道不存在 | 关联渠道已删除 | 联系管理员重新绑定渠道 |
| 素材分组远程同步暂只支持火山 provider | 当前仅支持火山素材库 | 使用火山引擎渠道 |
| 火山资源供应商 config 不是有效 JSON | 供应商 config 损坏 | 联系管理员修正 config |
| 火山素材库 AK/SK 未配置 | 供应商及渠道均无有效 AK/SK | 联系管理员配置 AK/SK |
| 资源供应商关联渠道未配置有效的火山 AK/SK | 渠道 Key 中解析不到 AK/SK | 联系管理员检查渠道凭据 |
6. 上游同步与绑定
| message | 原因说明 | 解决方案 |
|---|---|---|
| 资源分组未绑定对应供应商 group | 分组未与上游完成绑定 | 重新创建分组或联系管理员 |
| 已绑定供应商资源的记录暂不支持修改 group_id | 资源已绑定供应商不可换组 | 新建资源并指定目标分组 |
| 资源分组未绑定火山 group id | 更新分组时上游 group id 缺失 | 联系管理员检查绑定数据 |
| 资源未绑定火山 asset id | 更新资源时上游 asset id 缺失 | 联系管理员检查绑定数据 |
| 火山素材库返回的 asset id 为空 | 上游创建资源未返回 ID | 稍后重试，仍失败联系管理员 |
| 火山素材库返回的 group id 为空 | 上游创建分组未返回 ID | 稍后重试，仍失败联系管理员 |
| 火山素材库返回的 asset 为空 | 上游状态查询返回空 | 稍后重试，仍失败联系管理员 |
| 火山素材库返回为空 | 上游接口无响应 | 稍后重试，仍失败联系管理员 |
7. 上游素材库透传错误（HTTP 200 内）
| message | 原因说明 | 解决方案 |
|---|---|---|
| 火山素材库调用失败: {Code} | 火山方舟接口错误（凭据/参数/权限） | 依据上游 Message 修正，或联系管理员检查 AK/SK 权限 |
| 火山素材库资源状态查询超时: asset_id=xxx | 资源处理超过 2 分钟未就绪 | 稍后在资源列表查询状态 |
| 火山素材库资源处理失败: | 上游处理素材失败 | 检查资源 URL 后重新创建 |
| 火山素材库资源已可用但 URL 为空: asset_id=xxx | 上游异常 | 联系管理员排查 |
注意：创建资源是"先落库、后异步同步"，上游同步失败不会让创建接口报错，而是体现在资源
status=failed、message=失败原因，请在资源列表查询。
HTTP 400 · Bad Request（seedance 任务提交）
响应为 OpenAI 兼容格式，含 code 字段。
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
invalid_request | 请求体解析失败 | 请求体非法 JSON 或缺少必填字段（如 prompt） | 检查请求体格式与必填项 |
invalid_multipart_form | multipart 表单解析失败 | 表单格式错误 | 检查文件字段与请求格式 |
HTTP 403 · Forbidden（tkres_ 资源引用）
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
access_denied | 资源 {uuid} 不存在 | 引用的资源 UUID 不存在 | 通过资源列表确认 UUID |
access_denied | API Key 无权使用资源 {uuid} | 资源归属与 Key 租户 scope 不匹配 | 使用资源所属租户的 Key |
access_denied | 资源 {uuid} 未启用 | 资源同步中或同步失败 | 等待可用，或查看资源 message 失败原因 |
access_denied | 资源 {uuid} 未绑定当前渠道 | 当前渠道无该资源映射 | 使用资源所属供应商对应渠道 |
access_denied | 资源 {uuid} 的供应商资源ID为空 | 绑定数据异常 | 联系管理员 |
access_denied | 资源引用需要使用 API Key 访问 | 未携带 API Key | 改用 API Key 认证 |
access_denied | 资源引用替换缺少 channel_id | 请求未命中有效渠道 | 检查模型/渠道配置后重试 |
HTTP 500 · Internal Server Error（seedance 任务提交）
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
read_response_body_failed | 读取上游响应失败 | 上游返回异常 | 稍后重试，持续失败联系管理员 |
unmarshal_response_body_failed | 上游响应解析失败 | 上游响应格式异常 | 稍后重试，持续失败联系管理员 |
invalid_response | task_id 为空 | 上游未返回有效任务 ID | 稍后重试，持续失败联系管理员 |
附：任务失败状态码（查询任务时返回，非接口调用错误）
| code | message 含义 | 原因说明 | 解决方案 |
|---|---|---|---|
content_moderation | 内容审核未通过 | 提示词/素材命中审核规则 | 修改提示词或素材后重试 |
invalid_params | 参数无效 | 参数不被上游支持 | 按错误提示调整参数 |
generation_failed | 生成失败 | 上游生成失败 | 稍后重试 |
upload_failed | 上传失败 | 素材上传失败 | 检查素材 URL 后重试 |
model_unavailable | 模型不可用 | 模型资源暂时不可用 | 稍后重试或联系管理员 |
connection_failed | 连接失败 | 与上游连接异常 | 稍后重试，持续失败联系管理员 |
config_error | 配置错误 | 上游代理/配置异常 | 联系管理员 |
timeout | 任务超时 | 上游生成超时 | 稍后重试 |
auth_failed | 鉴权失败 | 上游 AK/SK 鉴权失败 | 联系管理员检查凭据 |
rate_limited | 触发限流 | 调用频率超限或上游限流 | 降低调用频率后重试 |