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
| Field | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded |
| error_code | string / null | Error code. null on success |
| error_msg | string / null | Error message. null on success |
| data | object / null | Business data. null on failure |
| request_id | string | Request ID, also returned in the X-Request-Id response header |
HTTP status codes
| HTTP status | Description |
|---|---|
| 400 | A request parameter is missing, malformed, or out of range |
| 401 | Identity information is missing or invalid |
| 500 | Business processing failed or an internal error occurred. error_code provides the specific reason |
Common error codes
| HTTP status | error_code | Description |
|---|---|---|
| 401 | WORKSPACE_ID_ILLEGAL | Identity information is missing or invalid |
| 400 | INVALID_PARAMETER | Invalid parameter format or value, or pagination is out of range |
| 400 | SKILL_ID_IS_NULL | skill_id is blank |
| 400 | SKILL_VERSION_IS_NULL | version is blank |
| 400 | SKILL_FILE_IS_NULL | file is not uploaded or the file is empty |
| 400 | SKILL_FILE_FORMATER_ERROR | The file extension is not .zip, or the file header is not in ZIP format |
| 400 | SKILL_PACKAGE_TOO_LARGE | The ZIP package exceeds 50MB |
| 500 | SKILL_FILE_FORMATER_ERROR | SKILL.md is missing, or the Front Matter lacks name or description |
| 500 | SKILL_PACKAGE_TOO_LARGE | The uncompressed content exceeds 100MB |
| 500 | SKILL_FILE_READ_ERROR | Failed to read the uploaded file or write it to storage |
| 500 | SKILL_EXTRA_ZIP_ERROR | Failed to unzip the package. Only UTF-8 or GBK file name encodings are supported |
| 500 | SKILL_NOT_EXIST | The Skill does not exist, is deleted, or is inaccessible |
| 500 | SKILL_VERSION_NOT_EXIST | The version does not exist, is deleted, or is invisible |
| 500 | SKILL_DELETE_OFFICIAL_NOT_ALLOWED | Attempted to delete an official Skill |
| 500 | SKILL_DELETE_ERROR | Failed to delete the Skill |
| 500 | SKILL_UPDATE_SECURITY_ERROR | The Skill is being security scanned and cannot accept a new version |
| 500 | SKILL_NAME_OFFICIAL_DUPLICATE | The name in SKILL.md duplicates an official Skill |
| 500 | SKILL_NAME_CUSTOMER_DUPLICATE | The name in SKILL.md duplicates a custom Skill in the current workspace |
| 500 | SKILL_SUBMIT_SECURITY_ERROR | Failed to submit the security scan |
| 500 | SKILL_INSERT_ERROR | Failed to save the Skill or version record |
| 500 | SKILL_UPDATE_LOCK_ERROR | A concurrent save operation conflicts on the same Skill |
| 500 | SYSTEM_ERROR | Internal service error |
Troubleshooting
- Use
request_idto locate the specific request. - Verify the API key, workspace ID, and endpoint. See Authentication.
- Before uploading a ZIP package, confirm that it is no larger than 50MB and contains
SKILL.md. - Query the Skill by
skill_idto confirm that no scan or concurrent operation is in progress.