# 錯誤代碼說明-API Endpoint 特定錯誤情境

本頁面整理各 API Endpoint 可能回傳的特定錯誤情境，方便開發者依照 API 用途快速查找常見錯誤代碼、理解可能原因，並進一步搭配錯誤代碼說明章節進行排查。

---

### 1. 說明目的

在 PrivAI 中，不同 API Endpoint 會對應不同的驗證邏輯、資源檢查與狀態限制，因此即使使用相同的錯誤代碼分類，不同 API 的實際觸發情境仍可能不同。

本頁面的目的如下：

| 項目 | 說明 |
| --- | --- |
| 依 API Endpoint 彙整錯誤 | 依據不同 API 的行為整理常見錯誤代碼 |
| 協助快速定位問題 | 讓前端、後端與客戶端工程師能快速判斷錯誤來源 |
| 搭配錯誤代碼頁面閱讀 | 可再配合各分類頁面理解錯誤代碼定義與排查方向 |
| 區分不同錯誤型態 | 區分同步 API 錯誤、資源狀態錯誤、參數驗證錯誤與資料不存在等情境 |

---

### 2. 使用方式

當呼叫某個 API 發生錯誤時，建議依下列順序排查：

| 步驟 | 說明 |
| --- | --- |
| 1 | 先確認呼叫的 Endpoint 與 HTTP Method 是否正確 |
| 2 | 對照本頁查看該 Endpoint 常見的錯誤代碼 |
| 3 | 再到對應的「錯誤代碼說明」頁面查閱該錯誤代碼的定義、HTTP Status 與排查建議 |
| 4 | 若為 Fileset Commit 或其他背景流程相關問題，除了 API response 外，也請搭配查詢資源本身的 `state`、`fail_reason`、`fail_detail` 等欄位確認實際失敗位置 |

---

### 3. 各 Endpoint 特定錯誤情境

#### 3.1 `/v1/chat/completions`（POST）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/chat/completions` |
| Method | `POST` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`VAL_003`、`VAL_004`、`VAL_005`、`FILE_002`、`FILE_007`、`PROMPT_001`、`FILESET_001`、`FILESET_006` |
| 錯誤情境 | 驗證相關問題；同時提供 `prompt` 與 `prompt_id`；`messages` 序列不符合規則；同時提供 `fileset_id` 與 `fileset_ids`；指定的 File 不存在；指定的 parsed result 不存在；指定的 Prompt 不存在；指定的 Fileset 不存在；指定的 Fileset 尚未完成，無法使用 |
| 補充說明 | 此 API 主要會檢查對話輸入格式、Prompt 來源、Fileset 狀態與 File 存在性。若使用 Fileset 作為檢索來源，需先確認 Fileset 已處於可用狀態。若使用 `fileset_ids` 指定多個 filesets，則任一 fileset 發生錯誤時，整個 request 會失敗。`fileset_ids: []` 不視為錯誤，而是視為未指定 fileset，不執行 RAG。 |

---

#### 3.2 `/v1/file`（GET）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/file` |
| Method | `GET` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`VAL_001`、`VAL_002` |
| 錯誤情境 | 驗證相關問題；同時提供 `before` 與 `after`；`before` 或 `after` 所指定的 cursor id 不存在 |
| 補充說明 | 此 API 主要與分頁參數有關，應避免同時提供互斥的 cursor 參數。 |

---

#### 3.3 `/v1/file`（POST）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/file` |
| Method | `POST` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILE_001`、`FILE_003` |
| 錯誤情境 | 驗證相關問題；不支援的檔案格式；File ID 已存在 |
| 補充說明 | 上傳檔案前請確認檔案型別是否為系統支援格式，並避免重複使用已存在的 File ID。 |

---

#### 3.4 `/v1/file/{file_id}`（GET）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/file/{file_id}` |
| Method | `GET` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILE_002` |
| 錯誤情境 | 驗證相關問題；File 不存在 |
| 補充說明 | 此 API 用於查詢單一檔案資訊，若回傳找不到檔案，請先確認 `file_id` 是否正確，或檔案是否已被刪除。 |

---

#### 3.5 `/v1/file/{file_id}`（DELETE）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/file/{file_id}` |
| Method | `DELETE` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILE_002`、`FILE_004` |
| 錯誤情境 | 驗證相關問題；File 不存在；該檔案仍被某個 Fileset 使用中 |
| 補充說明 | 若檔案仍綁定於 Fileset，系統將拒絕刪除。應先解除檔案與 Fileset 的關聯，或刪除相關 Fileset 後再操作。 |

---

#### 3.6 `/v1/file/{file_id}/content`（GET）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/file/{file_id}/content` |
| Method | `GET` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILE_002`、`FILE_007`、`FILE_008` |
| 錯誤情境 | 驗證相關問題；File 不存在；指定品質的 parsed result 不存在；指定品質的 chunks 不存在 |
| 補充說明 | 此 API 通常與檔案解析結果、chunk 結果有關。若指定某個品質模式（如 HQ / LQ / STD），但系統尚未產生該結果，就可能觸發錯誤。 |

---

#### 3.7 `/v1/filesets`（GET）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/filesets` |
| Method | `GET` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`VAL_001`、`VAL_002` |
| 錯誤情境 | 驗證相關問題；同時提供 `before` 與 `after`；`before` 或 `after` 所指定的 cursor id 不存在 |
| 補充說明 | 與檔案列表 API 類似，主要是分頁參數驗證。 |

---

#### 3.8 `/v1/filesets/{fileset_id}`（GET）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/filesets/{fileset_id}` |
| Method | `GET` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILESET_001` |
| 錯誤情境 | 驗證相關問題；Fileset 不存在 |
| 補充說明 | 若查不到 Fileset，請確認 `fileset_id` 是否正確，或該資源是否已被刪除。 |

---

#### 3.9 `/v1/filesets/{fileset_id}/files`（GET）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/filesets/{fileset_id}/files` |
| Method | `GET` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILESET_001`、`VAL_001`、`VAL_002` |
| 錯誤情境 | 驗證相關問題；Fileset 不存在；同時提供 `before` 與 `after`；`before` 或 `after` 所指定的 cursor id 不存在 |
| 補充說明 | 此 API 用於查看某個 Fileset 中的檔案列表與各檔案在該 Fileset 內的處理狀態。若查詢失敗，通常先檢查 Fileset 是否存在，其次檢查分頁參數是否合法。 |

---

#### 3.10 `/v1/filesets`（POST）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/filesets` |
| Method | `POST` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILESET_002`、`FILESET_008`、`FILE_002`、`FILE_009` |
| 錯誤情境 | 驗證相關問題；Fileset ID 已存在；部分 files 不存在；指定的 files 不存在 |
| 補充說明 | 建立 Fileset 時若直接綁定 files，系統會一併檢查所有 `file_id` 是否存在。若其中部分不存在，建立流程會失敗。 |

---

#### 3.11 `/v1/filesets/{fileset_id}`（PUT）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/filesets/{fileset_id}` |
| Method | `PUT` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILESET_001`、`FILESET_004`、`FILESET_007`、`FILESET_008`、`FILE_009` |
| 錯誤情境 | 驗證相關問題；Fileset 不存在；Fileset 狀態不允許更新；Version conflict；部分 files 不存在；指定的 files 不存在 |
| 補充說明 | 若 Fileset 已處於 `processing` 或 `completed` 等不可更新狀態，系統會拒絕修改。若有併發更新，也可能發生版本衝突。 |

---

#### 3.12 `/v1/filesets/{fileset_id}`（DELETE）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/filesets/{fileset_id}` |
| Method | `DELETE` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILESET_001` |
| 錯誤情境 | 驗證相關問題；Fileset 不存在 |
| 補充說明 | 若指定的 Fileset 不存在，刪除操作會失敗。 |

---

#### 3.13 `/v1/filesets/{fileset_id}/commit`（POST）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/filesets/{fileset_id}/commit` |
| Method | `POST` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILESET_001`、`FILESET_003`、`FILESET_005`、`FILESET_006`、`FILESET_007`、`FILESET_008` |
| 錯誤情境 | 驗證相關問題；Fileset 不存在；Fileset 目前狀態不可 commit；Fileset 內沒有任何檔案；Fileset 中存在不支援的檔案型別；Version conflict；部分 files 不存在 |
| 補充說明 | 這是知識版本建立流程中最重要的 API 之一。此 API 的同步錯誤主要來自 Fileset 狀態檢查、Fileset 內容是否合法、`file_id` 是否存在，以及資源版本是否衝突。若 commit API 已成功接受請求，但後續背景流程（例如 consumer、parse、split、indexing）失敗，錯誤不一定會直接由本 API response 回傳。此時建議改查 `GET /v1/filesets/{fileset_id}`、`GET /v1/filesets/{fileset_id}/files`、`GET /v1/files/{file_id}`，並搭配檢查 `state`、`fail_reason`、`fail_detail`。 |

---

#### 3.14 `/v1/filesets/{fileset_id}/duplicate`（POST）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/filesets/{fileset_id}/duplicate` |
| Method | `POST` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILESET_001`、`FILESET_002`、`FILE_009` |
| 錯誤情境 | 驗證相關問題；原始 Fileset 不存在；新的 Fileset ID 衝突；Files 不存在 |
| 補充說明 | 若複製來源 Fileset 本身不存在，或其所關聯的檔案資料異常，就可能發生此類錯誤。 |

---

#### 3.15 `/v1/models`（GET）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/models` |
| Method | `GET` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`MODEL_001` |
| 錯誤情境 | 驗證相關問題；模型服務或 LiteLLM 通訊異常（若系統實作有啟用此錯誤碼） |
| 補充說明 | 通常此 API 錯誤較少，若發生非驗證問題，多半與模型後端服務連線狀態有關。 |

---

#### 3.16 `/v1/prompts`（POST）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/prompts` |
| Method | `POST` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`PROMPT_002` |
| 錯誤情境 | 驗證相關問題；Prompt ID 已存在 |
| 補充說明 | 若建立時使用了已存在的 Prompt ID，系統會拒絕建立。 |

---

#### 3.17 `/v1/prompts`（GET）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/prompts` |
| Method | `GET` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`VAL_001`、`VAL_002` |
| 錯誤情境 | 驗證相關問題；同時提供 `before` 與 `after`；`before` 或 `after` 所指定的 cursor id 不存在 |
| 補充說明 | 主要與分頁查詢參數有關。 |

---

#### 3.18 `/v1/prompts/{prompt_id}`（GET）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/prompts/{prompt_id}` |
| Method | `GET` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`PROMPT_001` |
| 錯誤情境 | 驗證相關問題；Prompt 不存在 |
| 補充說明 | 若指定 Prompt 不存在，查詢會失敗。 |

---

#### 3.19 `/v1/prompts/{prompt_id}`（DELETE）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/prompts/{prompt_id}` |
| Method | `DELETE` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`PROMPT_001` |
| 錯誤情境 | 驗證相關問題；Prompt 不存在 |
| 補充說明 | 若指定 Prompt 不存在，刪除會失敗。 |

---

#### 3.20 `/v1/prompts/{prompt_id}/optimize/auto`（POST）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/prompts/{prompt_id}/optimize/auto` |
| Method | `POST` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`PROMPT_001` |
| 錯誤情境 | 驗證相關問題；Prompt 不存在 |
| 補充說明 | 若指定 Prompt 不存在，自動優化請求無法執行。 |

---

#### 3.21 `/v1/prompts/{prompt_id}/optimize/instruct`（POST）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/prompts/{prompt_id}/optimize/instruct` |
| Method | `POST` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`PROMPT_001` |
| 錯誤情境 | 驗證相關問題；Prompt 不存在 |
| 補充說明 | 若指定 Prompt 不存在，依指示優化請求無法執行。 |

---

#### 3.22 `/v1/qa/generate`（POST）

| 項目 | 內容 |
| --- | --- |
| Endpoint | `/v1/qa/generate` |
| Method | `POST` |
| 常見錯誤代碼 | `AUTH_001`、`AUTH_002`、`FILESET_001`、`FILESET_005`、`FILE_003`、`QA_001`、`QA_002` |
| 錯誤情境 | 驗證相關問題；Fileset 不存在；Fileset 內沒有任何檔案；File ID already exists；沒有產生任何 QA pairs；部分檔案產生 QA pairs 失敗 |
| 補充說明 | 此 API 與 Fileset 內容品質、檔案是否可正常解析，以及是否有足夠文本內容可生成問答有關。若部分檔案失敗，建議再進一步檢查各檔案狀態與內容品質。 |

---

### 4. 補充說明

#### 4.1 錯誤代碼分類規則

錯誤代碼依功能領域分類，格式為：

`{CATEGORY}_{NUMBER}`

| 類別 | 說明 |
| --- | --- |
| `AUTH` | 身份驗證相關錯誤 |
| `VAL` | 參數驗證相關錯誤 |
| `FILE` | 檔案管理相關錯誤 |
| `FILESET` | 知識版本管理相關錯誤 |
| `QA` | 問答生成相關錯誤 |
| `PROMPT` | 提示詞管理相關錯誤 |
| `MODEL` | 模型服務相關錯誤 |

---

#### 4.2 常見 HTTP Status 對應

| HTTP Status | 說明 |
| --- | --- |
| `400 Bad Request` | 請求本身不合法 |
| `401 Unauthorized` | 缺少授權資訊 |
| `403 Forbidden` | 授權失敗或無效 |
| `404 Not Found` | 資源不存在 |
| `409 Conflict` | 資源狀態衝突或版本衝突 |
| `415 Unsupported Media Type` | 不支援的檔案格式 |
| `422 Unprocessable Entity` | 參數驗證錯誤 |
| `500 Internal Server Error` | 系統內部錯誤 |

---

### 5. 建議閱讀順序

若你是第一次排查 API 錯誤，建議依照以下順序閱讀：

| 順序 | 建議內容 |
| --- | --- |
| 1 | 先看本頁，確認該 Endpoint 常見會出現哪些錯誤 |
| 2 | 再看各分類的「錯誤代碼說明」頁面，理解錯誤碼定義與 payload |
| 3 | 若涉及 Fileset Commit / 背景流程，再查看 Fileset State、Fileset File State、File metadata 中的 `fail_reason` / `fail_detail` |
