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

本頁依 API Endpoint 整理 PrivAI 4.0.0 各端點可能回傳的錯誤代碼與觸發情境，作為本章各錯誤代碼分類頁的交叉對照索引。

---

### 1. 使用方式

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

| 步驟 | 說明 |
| --- | --- |
| 1 | 先確認呼叫的 Endpoint 與 HTTP Method 是否正確（路徑皆為複數，例如 `/v1/files`、`/v1/filesets`、`/v1/prompts`） |
| 2 | 在本頁找到該 Endpoint，對照回應中的 `error_code` |
| 3 | 依「對照頁」欄位前往對應的錯誤代碼說明頁，查閱該錯誤代碼的 HTTP Status、錯誤訊息與 Inherent Payload |
| 4 | 若回應沒有 `error_code`（例如 422 `{"detail": [...]}`），請見 「例外狀況處理」 的「非錯誤代碼格式的回應」 |
| 5 | 若為 Fileset Commit 或其他背景流程問題，請改查資源的 `state` 與 `metadata.fail_detail`，見 「例外狀況處理」 |

---

### 2. 所有端點共通的錯誤

| 錯誤代碼 | 適用範圍 | 對照頁 |
| --- | --- | --- |
| `AUTH_001`、`AUTH_002`、`AUTH_003` | 使用 API Key 驗證的所有端點（下表以「AUTH」表示） | 「錯誤代碼說明-身份驗證類」 |
| `AUTH_001`、`AUTH_002` | `/v1/api-keys` 系列端點（使用 Admin Secret 驗證，不會有 `AUTH_003`） | 「錯誤代碼說明-身份驗證類」 |
| 無 | `POST /v1/mcp/tools/discover` 不需要 Authorization header |  |
| 422 `{"detail": [...]}`（無 `error_code`） | 所有端點：欄位型別、必填、enum、數值範圍或 UUID 格式驗證失敗 | 「例外狀況處理」 |

---

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

#### 3.1 API Key 管理

| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
| --- | --- | --- | --- |
| `POST /v1/api-keys` | `AUTH_001`、`AUTH_002` | 缺少 Authorization header；Admin Secret 不正確 | 「錯誤代碼說明-身份驗證類」 |
| `GET /v1/api-keys` | `AUTH_001`、`AUTH_002`、`VAL_001`、`VAL_002` | 驗證相關問題；同時提供 `before` 與 `after`；`before` 或 `after` 指定的 ID 不存在 | 「錯誤代碼說明-身份驗證類」、「錯誤代碼說明-傳遞參數驗證類」 |
| `PATCH /v1/api-keys/{id}`（`PUT` 為已棄用的相容路徑，行為相同） | `AUTH_001`、`AUTH_002`、`API_KEY_001` | 驗證相關問題；指定的 API Key `id` 不存在 | 「錯誤代碼說明-身份驗證類」 |

`expires_at` 必須是 ISO 8601 時間字串，格式錯誤時會得到 422 `{"detail": [...]}`。

#### 3.2 檔案管理

| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
| --- | --- | --- | --- |
| `GET /v1/files` | AUTH、`VAL_001`、`VAL_002` | 同時提供 `before` 與 `after`；cursor ID 不存在 | 「錯誤代碼說明-傳遞參數驗證類」 |
| `POST /v1/files` | AUTH、`FILE_001`、`FILE_003` | 不支援的檔案格式；指定的 File ID 已存在。另外 `metadata` 不是合法 JSON 物件，或 `instant_parse` 格式錯誤時，回傳 422 `{"detail": ...}` | 「錯誤代碼說明-檔案管理類」 |
| `GET /v1/files/{file_id}` | AUTH、`FILE_002` | File 不存在 | 「錯誤代碼說明-檔案管理類」 |
| `DELETE /v1/files/{file_id}` | AUTH、`FILE_004`、`FILE_002` | 檔案仍被 Fileset 使用（回應附帶 `fileset_ids`），需先從這些 Fileset 移除該檔案或刪除 Fileset；File 不存在 | 「錯誤代碼說明-檔案管理類」 |
| `POST /v1/files/{file_id}/parse` | AUTH、`FILE_002` | File 不存在。若同一檔案已在以相同模式解析中，不會回傳錯誤，而是回傳 200 與 `File {file_id} is already being parsed` | 「錯誤代碼說明-檔案管理類」 |
| `GET /v1/files/{file_id}/content` | AUTH、`FILE_002`、`FILE_007`、`FILE_008` | File 不存在；`file_type=parsed_result` 但指定 `quality` 的解析結果不存在；`file_type=chunks` 但指定 `quality` 的 chunks 不存在 | 「錯誤代碼說明-檔案管理類」 |

#### 3.3 知識版本管理

| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
| --- | --- | --- | --- |
| `GET /v1/filesets` | AUTH、`VAL_001`、`VAL_002` | 同時提供 `before` 與 `after`；cursor ID 不存在 | 「錯誤代碼說明-傳遞參數驗證類」 |
| `POST /v1/filesets` | AUTH、`FILESET_002`、`FILE_009` | Fileset ID 已存在；`file_ids` 中有不存在的檔案（回應附帶 `file_ids`） | 「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-檔案管理類」 |
| `GET /v1/filesets/{fileset_id}` | AUTH、`FILESET_001` | Fileset 不存在 | 「錯誤代碼說明-知識版本管理類」 |
| `PUT /v1/filesets/{fileset_id}` | AUTH、`FILESET_001`、`FILESET_004`、`FILE_009`、`FILESET_007` | Fileset 不存在；狀態為 `queued`／`processing`／`completed` 時嘗試變更 `file_ids`；`file_ids` 中有不存在的檔案；同時被其他請求修改（版本衝突） | 「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-檔案管理類」 |
| `DELETE /v1/filesets/{fileset_id}` | AUTH、`FILESET_001`、`FILESET_021` | Fileset 不存在；狀態為 `queued` 或 `processing`，無法刪除 | 「錯誤代碼說明-知識版本管理類」 |
| `GET /v1/filesets/{fileset_id}/files` | AUTH、`FILESET_001`、`VAL_001`、`VAL_002` | Fileset 不存在；同時提供 `before` 與 `after`；cursor ID 不存在 | 「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-傳遞參數驗證類」 |
| `POST /v1/filesets/{fileset_id}/commit` | AUTH、`FILESET_001`、`FILESET_005`、`FILESET_011`、`FILESET_003`、`FILESET_022`、`FILESET_007` | Fileset 不存在；Fileset 內沒有任何檔案；含不支援的檔案格式；狀態為 `queued`／`processing`／`completed` 或上一次 Commit 仍在執行；上一次 Commit 的取消清理尚未完成；版本衝突 | 「錯誤代碼說明-知識版本管理類」 |
| `DELETE /v1/filesets/{fileset_id}/commit` | AUTH、`FILESET_001`、`FILESET_009` | Fileset 不存在；狀態不是 `queued`／`processing`／`cancelled`（對已取消的 Fileset 重複呼叫會直接成功） | 「錯誤代碼說明-知識版本管理類」 |
| `POST /v1/filesets/{fileset_id}/duplicate` | AUTH、`FILESET_001`、`FILESET_002` | 來源 Fileset 不存在；request body 指定的新 Fileset ID 已存在 | 「錯誤代碼說明-知識版本管理類」 |

Commit API 成功時回傳 `202`，之後在背景執行的解析、切塊、Embedding 若失敗，錯誤不會由 Commit API 回傳。請改查 `GET /v1/filesets/{fileset_id}`、`GET /v1/filesets/{fileset_id}/files`、`GET /v1/files/{file_id}`，並檢查 `state` 與 `metadata.fail_detail`（見 「例外狀況處理」、「Fileset 知識版本建立流程」）。

#### 3.4 問答集生成

| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
| --- | --- | --- | --- |
| `POST /v1/qa/generate` | AUTH、`FILESET_001`、`FILESET_005`、`QA_001`、`QA_003` | Fileset 不存在；Fileset 內沒有任何檔案；所有檔案皆未產生 QA pairs；`on_oversize=fail` 時檔案內容過大，整批處理中止。部分檔案失敗時回傳 HTTP 400 但 body 為成功結構（`QA_002` 情境） | 「錯誤代碼說明-問答集生成類」、「錯誤代碼說明-知識版本管理類」 |

#### 3.5 提示詞管理

| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
| --- | --- | --- | --- |
| `GET /v1/prompts` | AUTH、`VAL_001`、`VAL_002` | 同時提供 `before` 與 `after`；cursor ID 不存在 | 「錯誤代碼說明-傳遞參數驗證類」 |
| `POST /v1/prompts` | AUTH、`PROMPT_002` | 指定的 Prompt ID 已存在 | 「錯誤代碼說明-提示詞管理類」 |
| `GET /v1/prompts/{prompt_id}` | AUTH、`PROMPT_001` | Prompt 不存在 | 「錯誤代碼說明-提示詞管理類」 |
| `DELETE /v1/prompts/{prompt_id}` | AUTH、`PROMPT_001` | Prompt 不存在 | 「錯誤代碼說明-提示詞管理類」 |
| `POST /v1/prompts/{prompt_id}/optimize/auto` | AUTH、`PROMPT_001` | 原始 Prompt 不存在。模型服務錯誤時回傳非錯誤代碼格式的回應 | 「錯誤代碼說明-提示詞管理類」 |
| `POST /v1/prompts/{prompt_id}/optimize/instruct` | AUTH、`PROMPT_001` | 原始 Prompt 不存在；缺少 `current_issue` 或 `desired_behavior` 時為 422 `{"detail": [...]}`。模型服務錯誤時回傳非錯誤代碼格式的回應 | 「錯誤代碼說明-提示詞管理類」 |

#### 3.6 模型

| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
| --- | --- | --- | --- |
| `GET /v1/models` | AUTH | 無法從模型服務取得清單時，沿用模型服務回傳的 HTTP Status，body 為 `{"detail": "LiteLLM API error: ..."}`（無 `error_code`） | 「例外狀況處理」 |

#### 3.7 對話與檢索

| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
| --- | --- | --- | --- |
| `POST /v1/chat/completions` | AUTH、`VAL_003`、`VAL_004`、`VAL_005` | 同時提供 `prompt` 與 `prompt_id`；`messages` 順序不符規則；同時提供 `fileset_id` 與 `fileset_ids` | 「錯誤代碼說明-傳遞參數驗證類」 |
| `POST /v1/chat/completions`（續） | `PROMPT_001`、`FILESET_001`、`FILESET_006`、`FILE_002`、`FILE_007`、`FILE_010` | `prompt_id` 指定的 Prompt 不存在；`fileset_ids` 中有 Fileset 不存在；有 Fileset 狀態不是 `completed`／`partial_failed`；`messages` 引用的檔案不存在、指定品質的解析結果不存在或內容為空 | 「錯誤代碼說明-提示詞管理類」、「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-檔案管理類」 |
| `POST /v1/chat/completions`（續） | `CHAT_001`、`CHAT_002`、`CHAT_003`、`CHAT_004`、`CHAT_005`、`CHAT_006` | 查詢內容過長；Reranker 或 Embedding 服務失敗；模型不支援圖片輸入或圖片無法辨識；圖片數量超過模型上限；其他無法歸類的模型服務或內部錯誤（`CHAT_006`，例如模型服務回傳錯誤）。`stream: true` 且串流已開始後發生的錯誤，會以 SSE `error` 事件送出。使用 MCP Tool 但無法連線至 MCP server 時，串流模式回傳 `CHAT_006`，非串流模式回傳 500（無 `error_code`） | 「錯誤代碼說明-Chat」 |
| `POST /v1/chat/references` | AUTH、`FILESET_001`、`FILESET_006`、`CHAT_001`、`CHAT_002`、`CHAT_003` | Fileset 不存在；Fileset 狀態不是 `completed`／`partial_failed`；查詢內容過長；Reranker 或 Embedding 服務失敗。缺少 query string 的 `fileset_id` 或 `query`、`fileset_id` 不是合法 UUID，或未送出 Request Body 時，回傳 422 `{"detail": [...]}` | 「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-Chat」 |
| `POST /v1/mcp/tools/discover` | 無 | 不需驗證。本端點不會回傳 PrivAI 錯誤代碼：`authorization` 與 `headers.Authorization` 同時提供等 request body 驗證失敗時回傳 422 `{"detail": [...]}`；無法連線至 MCP server、`server_url` 不是 http(s) 等執行期失敗一律回傳 500 | 「例外狀況處理」 |

在多 Filesets 模式下，`fileset_ids` 中任一 Fileset 不符合條件時整個 request 都會失敗；`fileset_ids: []` 不視為錯誤，而是視為未指定 Fileset，不執行 RAG。

#### 3.8 報告模板（Beta）

| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
| --- | --- | --- | --- |
| `POST /beta/report-generation/templates` | AUTH | 建立時只寫入模板並回傳 `201`。之後的背景解析若失敗（例如 `REPORT_TEMPLATE_005`），模板 `state` 會轉為 `failed` 並記錄於 `fail_detail`，可用取得模板 API 查詢 | 「錯誤代碼說明-建立報告模板」 |
| `GET /beta/report-generation/templates/{template_id}` | AUTH、`REPORT_TEMPLATE_003`、`REPORT_TEMPLATE_001` | `expand` 含不支援的欄位；模板不存在 | 「錯誤代碼說明-建立報告模板」 |
| `PATCH /beta/report-generation/templates/{template_id}` | AUTH、`REPORT_TEMPLATE_001`、`REPORT_TEMPLATE_002` | 模板不存在；模板狀態不是 `completed` | 「錯誤代碼說明-建立報告模板」 |
| `POST /beta/report-generation/templates/{template_id}/confirm` | AUTH、`REPORT_TEMPLATE_001`、`REPORT_TEMPLATE_002`、`REPORT_TEMPLATE_004` | 模板不存在；模板狀態不是 `pending_confirm`；`slots` 與 `jinja_html` 內的變數不一致 | 「錯誤代碼說明-建立報告模板」 |

#### 3.9 報告生成（Beta）

| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
| --- | --- | --- | --- |
| `POST /beta/report-generation/reports` | AUTH、`REPORT_GENERATION_004` | 以既有的 report `id` 重新建立，但該 report 狀態不是 `failed`。草稿生成在背景執行，失敗時 report `state` 轉為 `failed` 並記錄於 `fail_detail` | 「錯誤代碼說明-報告生成」 |
| `POST /beta/report-generation/reports/{report_id}/confirm` | AUTH、`REPORT_GENERATION_001`、`REPORT_GENERATION_004`、`REPORT_GENERATION_007` | Report 不存在；狀態不是 `pending_review` 或 `failed`；草稿為空或沒有章節 | 「錯誤代碼說明-報告生成」 |
| `DELETE /beta/report-generation/reports/{report_id}` | AUTH、`REPORT_GENERATION_001` | Report 不存在 | 「錯誤代碼說明-報告生成」 |
| `GET /beta/report-generation/reports/{report_id}` | AUTH、`REPORT_GENERATION_006`、`REPORT_GENERATION_001` | `expand` 含不支援的欄位；Report 不存在 | 「錯誤代碼說明-報告生成」 |
| `POST /beta/report-generation/reports/{report_id}/export` | AUTH、`REPORT_GENERATION_001`、`REPORT_GENERATION_004`、`FILE_002` | Report 不存在；狀態不是 `completed`；先前匯出的檔案已被刪除 | 「錯誤代碼說明-報告生成」、「錯誤代碼說明-檔案管理類」 |

---

### 4. 補充說明

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

錯誤代碼依功能領域分類，格式為 `{CATEGORY}_{NUMBER}`：

| 類別 | 說明 | 對照頁 |
| --- | --- | --- |
| `AUTH` | 身份驗證相關錯誤 | 「錯誤代碼說明-身份驗證類」 |
| `API_KEY` | API Key 管理相關錯誤（與身份驗證的 AUTH 類錯誤分開） | 「錯誤代碼說明-身份驗證類」 |
| `VAL` | 參數驗證相關錯誤 | 「錯誤代碼說明-傳遞參數驗證類」 |
| `FILE` | 檔案管理相關錯誤 | 「錯誤代碼說明-檔案管理類」 |
| `FILESET` | 知識版本管理相關錯誤 | 「錯誤代碼說明-知識版本管理類」 |
| `PROMPT` | 提示詞管理相關錯誤 | 「錯誤代碼說明-提示詞管理類」 |
| `QA` | 問答集生成相關錯誤 | 「錯誤代碼說明-問答集生成類」 |
| `CHAT` | 對話、檢索與上游模型服務相關錯誤 | 「錯誤代碼說明-Chat」 |
| `REPORT_TEMPLATE` | 報告模板相關錯誤 | 「錯誤代碼說明-建立報告模板」 |
| `REPORT_GENERATION` | 報告生成相關錯誤 | 「錯誤代碼說明-報告生成」 |

#### 4.2 常見 HTTP Status 對應

| HTTP Status | 說明 |
| --- | --- |
| `400 Bad Request` | 請求本身不合法，或資源內容不允許該操作（例如 Fileset 沒有檔案） |
| `401 Unauthorized` | 缺少授權資訊 |
| `403 Forbidden` | 授權無效或 API Key 已過期 |
| `404 Not Found` | 資源不存在 |
| `409 Conflict` | 資源狀態衝突、ID 重複或版本衝突 |
| `413 Content Too Large` | 查詢內容過長，或圖片數量超過模型上限 |
| `415 Unsupported Media Type` | 不支援的檔案格式，或模型不支援圖片輸入 |
| `422 Unprocessable Entity` | 參數驗證錯誤 |
| `500 Internal Server Error` | 系統內部錯誤 |
| `502 Bad Gateway` | 上游服務（模型、Embedding、Reranker）處理失敗 |

---

### 5. 建議閱讀順序

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

| 順序 | 建議內容 |
| --- | --- |
| 1 | 「例外狀況處理」：了解錯誤回應格式與背景流程錯誤的查詢方式 |
| 2 | 本頁：確認該 Endpoint 可能出現哪些錯誤 |
| 3 | 各分類的「錯誤代碼說明」頁面：理解錯誤代碼定義與 Inherent Payload |
| 4 | 若涉及 Fileset Commit／背景流程，再查看 「File Parse State、Fileset File State 與 Fileset State 的差異」 與檔案的 `metadata.fail_detail` |
