例外狀況處理
在 PrivAI 中,錯誤資訊分為兩種揭露方式:同步 API 錯誤回應 與 非同步背景流程錯誤資訊。本頁說明兩者的格式與排查方式;各錯誤代碼的定義請見本章各分類頁,依端點查詢請見 錯誤代碼說明-API Endpoint 特定錯誤情境。
同步 API 錯誤回應
當錯誤發生在 API 請求驗證或同步處理階段時,系統會以對應的 HTTP Status 回傳以下格式:
{
"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):
{
"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]:
{
"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 的差異。
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 | 額外的除錯資訊(不一定存在) |
{
"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 與後續查詢結果綜合判讀
建議排查順序
當發生錯誤時,建議依照以下順序進行排查:
-
先確認 API response 是否已直接回傳
error_code與error_message -
若有同步錯誤,先到「錯誤代碼說明-API Endpoint 特定錯誤情境」找到該端點,再依錯誤代碼確認請求參數、資源存在性與資源狀態
-
若回應沒有
error_code,對照上方「非錯誤代碼格式的回應」 -
若請求已成功送出但結果異常,請改查:
-
GET /v1/filesets/{fileset_id} -
GET /v1/filesets/{fileset_id}/files -
GET /v1/files/{file_id}
-
-
檢查:
-
state -
file_counts -
metadata.fail_detail
-
-
若為 Chat Completions + 多 Filesets 情境,請另外確認:
-
是否同時傳入
fileset_id與fileset_ids -
fileset_ids中是否包含不存在、或狀態不是completed/partial_failed的 Fileset -
是否誤將空陣列
[]當作 RAG 查詢來源
-