# 例外狀況處理

在 PrivAI 中，錯誤資訊分為兩種揭露方式：**同步 API 錯誤回應** 與 **非同步背景流程錯誤資訊**。本頁說明兩者的格式與排查方式；各錯誤代碼的定義請見本章各分類頁，依端點查詢請見 [錯誤代碼說明-API Endpoint 特定錯誤情境](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-api-endpoint-特定錯誤情境.md)。

---

### 同步 API 錯誤回應

當錯誤發生在 API 請求驗證或同步處理階段時，系統會以對應的 HTTP Status 回傳以下格式：

```json
{
  "error_code": "ERROR_CODE",
  "error_message": "Error message in English. Please refer to the API documentation.",
  "...": "依錯誤情境附帶的補充欄位（Inherent Payload）"
}
```

其中：

- `error_code`：提供可程式化處理的錯誤代碼，格式為 `{CATEGORY}_{NUMBER}`，例如 `FILESET_003`

- `error_message`：提供可讀性高的英文錯誤訊息。實際回傳的訊息一律會在各分類頁所列訊息後面附加 ` Please refer to the API documentation.`

- Inherent Payload：依錯誤情境附帶在最外層的補充欄位，例如 `state`、`file_ids`、`fileset_ids`、`fileset_id`、`quality`、`filetype`、`expected_state` 等，各錯誤代碼會附帶哪些欄位請見分類頁的「Inherent Payload」欄

範例（對處理中的 Fileset 再次 Commit）：

```json
{
  "error_code": "FILESET_003",
  "error_message": "Fileset cannot commit. Fileset is in processing state. Please refer to the API documentation.",
  "state": "processing"
}
```

建議以 `error_code` 判斷錯誤種類，不要比對 `error_message` 字串。

#### 常見同步錯誤情境

同步 API 錯誤通常包含以下類型：

- 身份驗證失敗，例如缺少 Authorization header、API Key 無效或已過期（見「錯誤代碼說明-身份驗證類」）

- 請求參數組合不合法，例如互斥欄位同時出現、cursor 參數不存在、`messages` 順序不符合規範（見「錯誤代碼說明-傳遞參數驗證類」）

- 指定的資源不存在，例如 File、Fileset、Prompt、Report 不存在

- 資源狀態不允許當前操作，例如 Fileset 處理中不可 commit、不可刪除，或 Fileset 尚未完成不可用於 RAG

- 請求內容不合法，例如上傳不支援的檔案格式

- 上游模型、Embedding 或 Reranker 服務異常（見「錯誤代碼說明-Chat」）

#### Chat Completions 與多 Filesets 的同步錯誤補充

在 Chat Completions 中使用 RAG 功能時，需注意以下規則：

- `fileset_id`（已棄用）與 `fileset_ids` 不可同時使用；若同時帶入，回傳 `VAL_005`

- `fileset_ids` 中任一 Fileset 不存在時回傳 `FILESET_001`；任一 Fileset 狀態不是 `completed` 或 `partial_failed` 時回傳 `FILESET_006`。只要有一個 Fileset 不符合，整個 request 就會失敗

- `fileset_ids: []` 不視為錯誤，系統會視為未指定 Fileset，不執行 RAG

#### 串流（stream）模式的錯誤

Chat Completions 使用 `stream: true` 時：

- 若錯誤發生在第一個回應片段送出之前，仍會以上述 HTTP 錯誤格式回傳

- 若錯誤發生在串流開始之後，HTTP Status 已是 200，錯誤會以一筆 SSE 事件送出，內容放在 `error` 物件中，之後緊接 `[DONE]`：

```json
{
  "error": {
    "message": "Failed to process the request. Please refer to the API documentation.",
    "type": "ChatUpstreamError",
    "code": "CHAT_006",
    "error_code": "CHAT_006",
    "error_message": "Failed to process the request. Please refer to the API documentation.",
    "upstream_message": "..."
  }
}
```

`error` 物件的格式與 OpenAI SDK 相容，使用 OpenAI SDK 串接時會被轉成 `openai.APIError`。

---

### 非錯誤代碼格式的回應

以下情況的回應**不帶** `error_code`，串接時請一併處理：

| 情況 | HTTP Status | 回應格式 |
| --- | --- | --- |
| 請求參數型別或必填欄位驗證失敗，例如 path 中的 ID 不是合法 UUID、缺少必填欄位、enum 值不合法、`limit` 超出範圍 | 422 | `{"detail": [{"type": "...", "loc": [...], "msg": "...", "input": ...}]}` |
| 端點自行回傳的簡易錯誤，例如「上傳檔案」的 `metadata` 不是合法 JSON 物件（422 `Invalid metadata format`）、「取得所有模型」無法取得模型清單（沿用模型服務回傳的 HTTP Status） | 依情況 | `{"detail": "..."}` |
| 模型服務拒絕請求，例如「提示詞自動優化」、「提示詞手動優化」指定了無法使用的 `model` | 422 | `{"detail": "openai.BadRequestError", "body": {...}}` |
| 「問答集生成」部分檔案產生失敗 | 400 | 與成功時相同的結構，另帶 `failed_file_ids` 與 `error_message`，詳見「錯誤代碼說明-問答集生成類」 |
| 其他未預期的伺服器錯誤 | 500 | `Internal Server Error`（純文字） |

---

### 非同步背景流程錯誤

當錯誤發生在請求已被接受之後的背景流程中，例如：

- 檔案解析（parse）失敗

- 切塊（split）失敗

- Embedding、寫入向量資料庫失敗

- Commit 被取消

此類錯誤無法由當次 API response 即時回傳（例如「Commit 知識版本」在請求被接受時即回傳 `202`）。系統會把錯誤紀錄寫入檔案的 `metadata.fail_detail`，並更新 File、Fileset File 與 Fileset 的狀態，供後續查詢。  
建議使用下列 API 查看背景流程的實際處理結果與失敗資訊：

- `GET /v1/filesets/{fileset_id}`：查看 Fileset 的 `state` 與 `file_counts`

- `GET /v1/filesets/{fileset_id}/files`：查看每個檔案在該 Fileset 中的 `state`，以及 `metadata.fail_detail`；可用 `files_state=failed` 只列出失敗的檔案

- `GET /v1/files/{file_id}`：查看單一檔案的 `metadata.parsed_results` 與 `metadata.fail_detail`

若 Commit 或檔案轉換時有帶 `webhook_url`，處理結束時系統也會將結果通知該 URL。  
若 Fileset 最終狀態為 `failed`、`partial_failed` 或 `cancelled`，請再查看相關檔案的 `metadata.fail_detail`。各狀態的意義請見 [File Parse State、Fileset File State 與 Fileset State 的差異](https://privstation-docs.apmic.ai/latest/privai-400/file-parse-statefileset-file-state-與-fileset-state-的差異.md)。

---

### fail_detail

`metadata.fail_detail` 是一個陣列，每次背景流程失敗都會在最前面新增一筆紀錄（最新的在第一筆）。每筆紀錄的欄位如下：

| Field | Type | Detail |
| --- | --- | --- |
| timestamp | string (ISO 8601) | 發生時間 |
| error_type | string | 錯誤類型名稱，例如 `EmptyParsedResultError`、`TableRowTooLongError`、`CancelledError`。與錯誤代碼的對照請見各分類頁的「背景流程與保留錯誤代碼」表 |
| error_message | string | 錯誤訊息 |
| reason | string | 失敗原因摘要，例如 `parsing_error`、`LQ_parsing_error`、`splitting_error`、`embedding_error`、`save_to_lancedb_error`、`finalize_file_error`、`cancelled`（不一定存在） |
| step | string | 失敗的處理步驟，例如 `parse`、`parse_lq`、`split`、`embed`、`cancel`（不一定存在） |
| extra | object | 額外的除錯資訊（不一定存在） |

```json
{
  "metadata": {
    "fail_detail": [
      {
        "timestamp": "2026-09-30T08:12:45.123456+00:00",
        "error_type": "EmptyParsedResultError",
        "error_message": "Parsed result is empty. Please refer to the API documentation.",
        "reason": "parsing_error",
        "step": "parse"
      }
    ]
  }
}
```

#### 使用建議

- 需要快速判斷「在哪個階段失敗」時，優先查看 `reason` 與 `step`

- 需要定位更細的錯誤來源時，查看 `error_type` 與 `error_message`

- 若同時存在同步錯誤與背景流程失敗資訊，應以實際 API response 與後續查詢結果綜合判讀

---

### 建議排查順序

當發生錯誤時，建議依照以下順序進行排查：

1. 先確認 API response 是否已直接回傳 `error_code` 與 `error_message`

1. 若有同步錯誤，先到「錯誤代碼說明-API Endpoint 特定錯誤情境」找到該端點，再依錯誤代碼確認請求參數、資源存在性與資源狀態

1. 若回應沒有 `error_code`，對照上方「非錯誤代碼格式的回應」

1. 若請求已成功送出但結果異常，請改查：

    - `GET /v1/filesets/{fileset_id}`

    - `GET /v1/filesets/{fileset_id}/files`

    - `GET /v1/files/{file_id}`

1. 檢查：

    - `state`

    - `file_counts`

    - `metadata.fail_detail`

1. 若為 Chat Completions + 多 Filesets 情境，請另外確認：

    - 是否同時傳入 `fileset_id` 與 `fileset_ids`

    - `fileset_ids` 中是否包含不存在、或狀態不是 `completed` / `partial_failed` 的 Fileset

    - 是否誤將空陣列 `[]` 當作 RAG 查詢來源
