Skip to main content

Skill API 错误码

Skill API 的错误响应结构、常见错误码和排查建议。

Skill API 的成功响应和业务错误使用统一响应结构。

响应结构

字段类型说明
successboolean请求是否成功
error_codestring / null错误码,成功时为 null
error_msgstring / null错误信息,成功时为 null
dataobject / null业务数据,失败时为 null
request_idstring请求 ID,同时通过响应头 X-Request-Id 返回
{
  "success": false,
  "error_code": "SKILL_NOT_EXIST",
  "error_msg": "skill不存在",
  "data": null,
  "request_id": "15a89d4c-f142-4e00-a9f7-b088442417c9"
}

HTTP 状态码

HTTP 状态码说明
400请求参数缺失、格式错误或超出取值范围
401身份信息缺失或无效
500业务处理失败或服务内部错误,error_code 给出具体原因

常见错误码

HTTP 状态码error_code说明
401WORKSPACE_ID_ILLEGAL身份信息缺失或无效
400INVALID_PARAMETER参数格式错误、取值不合法或分页超出范围
400SKILL_ID_IS_NULLskill_id 为空白
400SKILL_VERSION_IS_NULLversion 为空白
400SKILL_FILE_IS_NULL未上传 file 或文件为空
400SKILL_FILE_FORMATER_ERROR文件扩展名不是 .zip,或文件头不是 ZIP 格式
400SKILL_PACKAGE_TOO_LARGEZIP 包超过 50MB
500SKILL_FILE_FORMATER_ERROR缺少 SKILL.md,或 Front Matter 缺少 name 或 description
500SKILL_PACKAGE_TOO_LARGEZIP 解压后累计大小超过 100MB
500SKILL_FILE_READ_ERROR读取上传文件或写入存储失败
500SKILL_EXTRA_ZIP_ERRORZIP 解压失败,仅支持 UTF-8 或 GBK 文件名编码
500SKILL_NOT_EXISTSkill 不存在、已删除或无权访问
500SKILL_VERSION_NOT_EXIST版本不存在、已删除或不可见
500SKILL_DELETE_OFFICIAL_NOT_ALLOWED尝试删除官方 Skill
500SKILL_DELETE_ERROR删除 Skill 失败
500SKILL_UPDATE_SECURITY_ERRORSkill 正在安全扫描中,暂不能创建新版本
500SKILL_NAME_OFFICIAL_DUPLICATESKILL.md 的 name 与官方 Skill 重名
500SKILL_NAME_CUSTOMER_DUPLICATESKILL.md 的 name 与当前空间的自定义 Skill 重名
500SKILL_SUBMIT_SECURITY_ERROR提交安全扫描失败
500SKILL_INSERT_ERROR保存 Skill 或版本记录失败
500SKILL_UPDATE_LOCK_ERROR同一 Skill 的保存操作并发冲突
500SYSTEM_ERROR服务内部错误

排查建议

  1. 使用 request_id 定位具体请求。
  2. 检查 API Key、工作空间 ID 和 Endpoint 是否正确,详见认证。
  3. 上传 ZIP 包前确认文件不超过 50MB,且包内包含 SKILL.md。
  4. 按 skill_id 查询 Skill 状态,确认无正在进行的扫描或并发操作。