# 錯誤代碼說明-知識版本管理類

### API 回應中的錯誤代碼

以下錯誤代碼會出現在同步 API 回應中，回應格式見 [例外狀況處理](https://privstation-docs.apmic.ai/latest/privai-400/例外狀況處理.md)。Fileset 各狀態的意義請見 [File Parse State、Fileset File State 與 Fileset State 的差異](https://privstation-docs.apmic.ai/latest/privai-400/file-parse-statefileset-file-state-與-fileset-state-的差異.md)。

| Error Code | HTTP Status | Scenario | Error Message | Inherent Payload |
| --- | --- | --- | --- | --- |
| `FILESET_001` | 404 | 指定的 Fileset 不存在、已被刪除，或不屬於目前的 API Key | Fileset not found. | 部分端點（如 `/v1/qa/generate`）會附帶 "fileset_id": uuid |
| `FILESET_002` | 409 | 建立或複製 Fileset 時指定的 `id` 已存在 | Fileset ID already exists. |  |
| `FILESET_003` | 409 | Commit 時 Fileset 狀態為 `queued`、`processing` 或 `completed`；或上一次 Commit 的背景流程仍在執行 | Fileset cannot commit. Fileset is in {state} state. | "state": string |
| `FILESET_004` | 409 | 更新 Fileset 時狀態為 `queued`、`processing` 或 `completed`，且 `file_ids` 與現有檔案不同（這些狀態下仍可只更新 `name` 與 `metadata`） | Fileset cannot update. | "state": string |
| `FILESET_005` | 400 | Commit 或產生問答集時，Fileset 內沒有任何檔案 | Fileset must contain at least one file. | `/v1/qa/generate` 會附帶 "fileset_id": uuid |
| `FILESET_006` | 409 | Chat Completions 或資料參考搜尋指定的 Fileset 狀態不是 `completed` 或 `partial_failed`，無法用於檢索 | Cannot use fileset. | "state": string, "fileset_id": uuid |
| `FILESET_007` | 409 | 更新或 Commit 時，Fileset 已被其他請求同時修改（版本衝突） | Version conflict: The resource has been modified by another request. |  |
| `FILESET_009` | 409 | 取消 Commit 時 Fileset 狀態不是 `queued`、`processing` 或 `cancelled`（例如 `draft`、`completed`、`failed`、`partial_failed`），或 Commit 已在取消請求送達前結束。對已是 `cancelled` 的 Fileset 重複取消會直接成功，不會回傳此錯誤 | Fileset cannot be cancelled. | "state": string |
| `FILESET_011` | 400 | Commit 時 Fileset 中有檔案的 `filetype` 不在支援清單中 | Unsupported file type: {filetype} | "filetype": string |
| `FILESET_021` | 409 | 刪除 Fileset 時狀態為 `queued` 或 `processing` | Fileset cannot be deleted. Fileset is in {state} state. | "state": string |
| `FILESET_022` | 409 | 對已取消的 Fileset 重新 Commit 時，上一次 Commit 的取消清理尚未完成；請稍候再試 | Fileset commit is still being cancelled. Please wait for the cancellation to finish before committing again. |  |

`FILESET_008`（Contains non-exist files）已不存在於 4.0.0，「`file_ids` 中有不存在的檔案」請改看 `FILE_009`（見「錯誤代碼說明-檔案管理類」）。

### 背景流程與保留錯誤代碼

以下錯誤代碼仍定義於 4.0.0，但不會出現在同步 API 回應中。背景流程失敗時，錯誤會以「錯誤類型名稱」記錄在檔案的 `metadata.fail_detail[].error_type`（見「例外狀況處理」章節），下表提供對照。

| Error Code | error_type | HTTP Status | Error Message | 說明 |
| --- | --- | --- | --- | --- |
| `FILESET_018` | NoChunkError | 500 | No chunks found in the file splitting result. | Commit 背景流程中，檔案切塊後沒有產生任何 chunk |
| `FILESET_020` | TableRowTooLongError | 400 | Table row is longer than max chunk size, cannot be split into chunks. | Commit 背景流程中，表格單列內容超過 chunk 長度上限，無法切塊 |
| `FILESET_010` | LockFilesetFailedError | 409 | Fileset cannot be locked. | 舊版 Commit 流程使用，4.0.0 不會產生；僅可能出現在歷史紀錄中 |
| `FILESET_012` | FileNotParsedYetError | 400 | File is not parsed yet. | 同上 |
| `FILESET_013` | FileMissingChunksMetadataError | 400 | File is missing chunks metadata. | 同上 |
| `FILESET_014` | FileMissingChunksURLError | 400 | File is missing chunks URL. | 同上 |
| `FILESET_015` | FileMissingEmbeddingsCacheError | 400 | File is missing embeddings cache. | 同上 |
| `FILESET_016` | FileMissingUsedQualityError | 400 | File is missing used quality. | 同上 |
| `FILESET_017` | ConflictFileNotFoundInFilesetError | 404 | Conflict file not found in fileset. | 同上 |
| `FILESET_019` | NotAllFilesCompletedError | 500 | Not all files are completed for fileset {fileset_id}: {processed}/{total} processed | 同上 |
