Skip to main content

Skill API error codes

Error response structure, common error codes, and troubleshooting for the Skill API.

Successful responses and business errors of the Skill API share a unified response structure.

Response structure

FieldTypeDescription
successbooleanWhether the request succeeded
error_codestring / nullError code. null on success
error_msgstring / nullError message. null on success
dataobject / nullBusiness data. null on failure
request_idstringRequest ID, also returned in the X-Request-Id response header
{
  "success": false,
  "error_code": "SKILL_NOT_EXIST",
  "error_msg": "skill不存在",
  "data": null,
  "request_id": "15a89d4c-f142-4e00-a9f7-b088442417c9"
}

HTTP status codes

HTTP statusDescription
400A request parameter is missing, malformed, or out of range
401Identity information is missing or invalid
500Business processing failed or an internal error occurred. error_code provides the specific reason

Common error codes

HTTP statuserror_codeDescription
401WORKSPACE_ID_ILLEGALIdentity information is missing or invalid
400INVALID_PARAMETERInvalid parameter format or value, or pagination is out of range
400SKILL_ID_IS_NULLskill_id is blank
400SKILL_VERSION_IS_NULLversion is blank
400SKILL_FILE_IS_NULLfile is not uploaded or the file is empty
400SKILL_FILE_FORMATER_ERRORThe file extension is not .zip, or the file header is not in ZIP format
400SKILL_PACKAGE_TOO_LARGEThe ZIP package exceeds 50MB
500SKILL_FILE_FORMATER_ERRORSKILL.md is missing, or the Front Matter lacks name or description
500SKILL_PACKAGE_TOO_LARGEThe uncompressed content exceeds 100MB
500SKILL_FILE_READ_ERRORFailed to read the uploaded file or write it to storage
500SKILL_EXTRA_ZIP_ERRORFailed to unzip the package. Only UTF-8 or GBK file name encodings are supported
500SKILL_NOT_EXISTThe Skill does not exist, is deleted, or is inaccessible
500SKILL_VERSION_NOT_EXISTThe version does not exist, is deleted, or is invisible
500SKILL_DELETE_OFFICIAL_NOT_ALLOWEDAttempted to delete an official Skill
500SKILL_DELETE_ERRORFailed to delete the Skill
500SKILL_UPDATE_SECURITY_ERRORThe Skill is being security scanned and cannot accept a new version
500SKILL_NAME_OFFICIAL_DUPLICATEThe name in SKILL.md duplicates an official Skill
500SKILL_NAME_CUSTOMER_DUPLICATEThe name in SKILL.md duplicates a custom Skill in the current workspace
500SKILL_SUBMIT_SECURITY_ERRORFailed to submit the security scan
500SKILL_INSERT_ERRORFailed to save the Skill or version record
500SKILL_UPDATE_LOCK_ERRORA concurrent save operation conflicts on the same Skill
500SYSTEM_ERRORInternal service error

Troubleshooting

  1. Use request_id to locate the specific request.
  2. Verify the API key, workspace ID, and endpoint. See Authentication.
  3. Before uploading a ZIP package, confirm that it is no larger than 50MB and contains SKILL.md.
  4. Query the Skill by skill_id to confirm that no scan or concurrent operation is in progress.