# 例外狀況處理

在 PrivAI 中，錯誤資訊分為兩種揭露方式：**同步 API 錯誤回應** 與 **非同步背景流程錯誤資訊**。

---

### 同步 API 錯誤回應

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

```text
{
  "error_message":"Error message in English",
  "error_code":"ERROR_CODE",
  ...(Inherent Payload)
}
```

其中：

- `error_message`：提供可讀性高的英文錯誤訊息

- `error_code`：提供可程式化處理的錯誤代碼

- `Inherent Payload`：依錯誤情境附帶的補充欄位，例如 `state`、`file_ids`、`fileset_id`、`quality` 等

若遇到 API 回傳此類錯誤，請查閱 9. 錯誤代碼說明。

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

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

- 身份驗證失敗，例如缺少 Authorization header 或 API Key 無效

- 請求參數格式錯誤，例如互斥欄位同時出現或 cursor 參數不合法

- 指定的資源不存在，例如 file、fileset、prompt 不存在

- 資源狀態不允許當前操作，例如 fileset 尚未完成、fileset 不可 commit 或不可 update

- 請求內容不合法，例如上傳不支援的檔案格式或 messages 結構不符合規範

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

在 Chat Completions API 中，若使用 RAG 功能，除了既有的 fileset 驗證外，也需注意以下規則：

- `fileset_id` 與 `fileset_ids` 不可同時使用；若同時帶入，系統會回傳同步錯誤

- `fileset_ids` 中任一 fileset 不存在、不可使用或狀態異常時，整個 request 會失敗

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

---

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

當錯誤發生在 commit 已提交後的背景流程中，例如：

- consumer 執行失敗

- parse 失敗

- split 失敗

- indexing / embedding 失敗

- 其他非同步後處理失敗

此類錯誤通常無法由當次 API response 即時回傳。

因此系統會將錯誤資訊寫入 File 或 Fileset 關聯資料中，供後續查詢。

建議使用下列 API 查看背景流程的實際處理結果與失敗資訊：

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

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

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

#### 補充說明

非同步背景流程錯誤主要出現在知識版本建立與檔案處理流程中。

這類錯誤與一般聊天 API 的同步驗證錯誤不同，通常代表：

- 請求本身已被接受

- 但後續背景工作在執行過程中失敗

- 因此需要改由查詢資源狀態與 metadata 來判斷實際失敗原因

若 Fileset 最終狀態為 `failed`、`partial_failed` 或 `cancelled`，建議再進一步查看相關 File 或 Fileset File 的失敗資訊。

---

### fail_reason 與 fail_detail

為了讓使用者與工程師都能更快理解問題，系統會在 metadata 中保留以下欄位：

- `fail_reason`：適合直接顯示給使用者或客戶端工程師閱讀的失敗原因摘要

- `fail_detail`：較完整的錯誤細節、處理歷史、內部流程資訊或 fallback 原因，便於除錯與排查

#### 使用建議

- 當使用者需要快速理解「發生了什麼問題」時，優先查看 `fail_reason`

- 當工程師需要定位更細的錯誤來源或追查背景流程失敗原因時，建議查看 `fail_detail`

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

若遇到同步 API 錯誤，請查閱 錯誤代碼說明章節。

若 API 已成功接受請求但後續流程仍失敗，請優先查詢相關資源的 metadata 欄位。

---

### 建議排查順序

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

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

1. 若有同步錯誤，先根據錯誤代碼確認請求參數、資源存在性與資源狀態

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

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

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

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

1. 檢查：

- `state`

- `file_counts`

- `metadata.fail_reason`

- `metadata.fail_detail`

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

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

- `fileset_ids` 中是否包含不存在或不可用的 fileset

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