跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

例外狀況處理

在 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": "..."}
模型服務拒絕請求,例如「提示詞自動優化」、「提示詞手動優化」指定了無法使用的 model422{"detail": "openai.BadRequestError", "body": {...}}
「問答集生成」部分檔案產生失敗400與成功時相同的結構,另帶 failed_file_ids 與 error_message,詳見「錯誤代碼說明-問答集生成類」
其他未預期的伺服器錯誤500Internal 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 是一個陣列,每次背景流程失敗都會在最前面新增一筆紀錄(最新的在第一筆)。每筆紀錄的欄位如下:

FieldTypeDetail
timestampstring (ISO 8601)發生時間
error_typestring錯誤類型名稱,例如 EmptyParsedResultError、TableRowTooLongError、CancelledError。與錯誤代碼的對照請見各分類頁的「背景流程與保留錯誤代碼」表
error_messagestring錯誤訊息
reasonstring失敗原因摘要,例如 parsing_error、LQ_parsing_error、splitting_error、embedding_error、save_to_lancedb_error、finalize_file_error、cancelled(不一定存在)
stepstring失敗的處理步驟,例如 parse、parse_lq、split、embed、cancel(不一定存在)
extraobject額外的除錯資訊(不一定存在)
{
"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

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

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

  4. 若請求已成功送出但結果異常,請改查:

    • GET /v1/filesets/{fileset_id}

    • GET /v1/filesets/{fileset_id}/files

    • GET /v1/files/{file_id}

  5. 檢查:

    • state

    • file_counts

    • metadata.fail_detail

  6. 若為 Chat Completions + 多 Filesets 情境,請另外確認:

    • 是否同時傳入 fileset_id 與 fileset_ids

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

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