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

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

本頁面整理各 API Endpoint 可能回傳的特定錯誤情境,方便開發者依照 API 用途快速查找常見錯誤代碼、理解可能原因,並進一步搭配錯誤代碼說明章節進行排查。


1. 說明目的​

在 PrivAI 中,不同 API Endpoint 會對應不同的驗證邏輯、資源檢查與狀態限制,因此即使使用相同的錯誤代碼分類,不同 API 的實際觸發情境仍可能不同。

本頁面的目的如下:

項目說明
依 API Endpoint 彙整錯誤依據不同 API 的行為整理常見錯誤代碼
協助快速定位問題讓前端、後端與客戶端工程師能快速判斷錯誤來源
搭配錯誤代碼頁面閱讀可再配合各分類頁面理解錯誤代碼定義與排查方向
區分不同錯誤型態區分同步 API 錯誤、資源狀態錯誤、參數驗證錯誤與資料不存在等情境

2. 使用方式​

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

步驟說明
1先確認呼叫的 Endpoint 與 HTTP Method 是否正確
2對照本頁查看該 Endpoint 常見的錯誤代碼
3再到對應的「錯誤代碼說明」頁面查閱該錯誤代碼的定義、HTTP Status 與排查建議
4若為 Fileset Commit 或其他背景流程相關問題,除了 API response 外,也請搭配查詢資源本身的 state、fail_reason、fail_detail 等欄位確認實際失敗位置

3. 各 Endpoint 特定錯誤情境​

3.1 /v1/chat/completions(POST)​

項目內容
Endpoint/v1/chat/completions
MethodPOST
常見錯誤代碼AUTH_001、AUTH_002、VAL_003、VAL_004、VAL_005、FILE_002、FILE_007、PROMPT_001、FILESET_001、FILESET_006
錯誤情境驗證相關問題;同時提供 prompt 與 prompt_id;messages 序列不符合規則;同時提供 fileset_id 與 fileset_ids;指定的 File 不存在;指定的 parsed result 不存在;指定的 Prompt 不存在;指定的 Fileset 不存在;指定的 Fileset 尚未完成,無法使用
補充說明此 API 主要會檢查對話輸入格式、Prompt 來源、Fileset 狀態與 File 存在性。若使用 Fileset 作為檢索來源,需先確認 Fileset 已處於可用狀態。若使用 fileset_ids 指定多個 filesets,則任一 fileset 發生錯誤時,整個 request 會失敗。fileset_ids: [] 不視為錯誤,而是視為未指定 fileset,不執行 RAG。

3.2 /v1/file(GET)​

項目內容
Endpoint/v1/file
MethodGET
常見錯誤代碼AUTH_001、AUTH_002、VAL_001、VAL_002
錯誤情境驗證相關問題;同時提供 before 與 after;before 或 after 所指定的 cursor id 不存在
補充說明此 API 主要與分頁參數有關,應避免同時提供互斥的 cursor 參數。

3.3 /v1/file(POST)​

項目內容
Endpoint/v1/file
MethodPOST
常見錯誤代碼AUTH_001、AUTH_002、FILE_001、FILE_003
錯誤情境驗證相關問題;不支援的檔案格式;File ID 已存在
補充說明上傳檔案前請確認檔案型別是否為系統支援格式,並避免重複使用已存在的 File ID。

3.4 /v1/file/{file_id}(GET)​

項目內容
Endpoint/v1/file/{file_id}
MethodGET
常見錯誤代碼AUTH_001、AUTH_002、FILE_002
錯誤情境驗證相關問題;File 不存在
補充說明此 API 用於查詢單一檔案資訊,若回傳找不到檔案,請先確認 file_id 是否正確,或檔案是否已被刪除。

3.5 /v1/file/{file_id}(DELETE)​

項目內容
Endpoint/v1/file/{file_id}
MethodDELETE
常見錯誤代碼AUTH_001、AUTH_002、FILE_002、FILE_004
錯誤情境驗證相關問題;File 不存在;該檔案仍被某個 Fileset 使用中
補充說明若檔案仍綁定於 Fileset,系統將拒絕刪除。應先解除檔案與 Fileset 的關聯,或刪除相關 Fileset 後再操作。

3.6 /v1/file/{file_id}/content(GET)​

項目內容
Endpoint/v1/file/{file_id}/content
MethodGET
常見錯誤代碼AUTH_001、AUTH_002、FILE_002、FILE_007、FILE_008
錯誤情境驗證相關問題;File 不存在;指定品質的 parsed result 不存在;指定品質的 chunks 不存在
補充說明此 API 通常與檔案解析結果、chunk 結果有關。若指定某個品質模式(如 HQ / LQ / STD),但系統尚未產生該結果,就可能觸發錯誤。

3.7 /v1/filesets(GET)​

項目內容
Endpoint/v1/filesets
MethodGET
常見錯誤代碼AUTH_001、AUTH_002、VAL_001、VAL_002
錯誤情境驗證相關問題;同時提供 before 與 after;before 或 after 所指定的 cursor id 不存在
補充說明與檔案列表 API 類似,主要是分頁參數驗證。

3.8 /v1/filesets/{fileset_id}(GET)​

項目內容
Endpoint/v1/filesets/{fileset_id}
MethodGET
常見錯誤代碼AUTH_001、AUTH_002、FILESET_001
錯誤情境驗證相關問題;Fileset 不存在
補充說明若查不到 Fileset,請確認 fileset_id 是否正確,或該資源是否已被刪除。

3.9 /v1/filesets/{fileset_id}/files(GET)​

項目內容
Endpoint/v1/filesets/{fileset_id}/files
MethodGET
常見錯誤代碼AUTH_001、AUTH_002、FILESET_001、VAL_001、VAL_002
錯誤情境驗證相關問題;Fileset 不存在;同時提供 before 與 after;before 或 after 所指定的 cursor id 不存在
補充說明此 API 用於查看某個 Fileset 中的檔案列表與各檔案在該 Fileset 內的處理狀態。若查詢失敗,通常先檢查 Fileset 是否存在,其次檢查分頁參數是否合法。

3.10 /v1/filesets(POST)​

項目內容
Endpoint/v1/filesets
MethodPOST
常見錯誤代碼AUTH_001、AUTH_002、FILESET_002、FILESET_008、FILE_002、FILE_009
錯誤情境驗證相關問題;Fileset ID 已存在;部分 files 不存在;指定的 files 不存在
補充說明建立 Fileset 時若直接綁定 files,系統會一併檢查所有 file_id 是否存在。若其中部分不存在,建立流程會失敗。

3.11 /v1/filesets/{fileset_id}(PUT)​

項目內容
Endpoint/v1/filesets/{fileset_id}
MethodPUT
常見錯誤代碼AUTH_001、AUTH_002、FILESET_001、FILESET_004、FILESET_007、FILESET_008、FILE_009
錯誤情境驗證相關問題;Fileset 不存在;Fileset 狀態不允許更新;Version conflict;部分 files 不存在;指定的 files 不存在
補充說明若 Fileset 已處於 processing 或 completed 等不可更新狀態,系統會拒絕修改。若有併發更新,也可能發生版本衝突。

3.12 /v1/filesets/{fileset_id}(DELETE)​

項目內容
Endpoint/v1/filesets/{fileset_id}
MethodDELETE
常見錯誤代碼AUTH_001、AUTH_002、FILESET_001
錯誤情境驗證相關問題;Fileset 不存在
補充說明若指定的 Fileset 不存在,刪除操作會失敗。

3.13 /v1/filesets/{fileset_id}/commit(POST)​

項目內容
Endpoint/v1/filesets/{fileset_id}/commit
MethodPOST
常見錯誤代碼AUTH_001、AUTH_002、FILESET_001、FILESET_003、FILESET_005、FILESET_006、FILESET_007、FILESET_008
錯誤情境驗證相關問題;Fileset 不存在;Fileset 目前狀態不可 commit;Fileset 內沒有任何檔案;Fileset 中存在不支援的檔案型別;Version conflict;部分 files 不存在
補充說明這是知識版本建立流程中最重要的 API 之一。此 API 的同步錯誤主要來自 Fileset 狀態檢查、Fileset 內容是否合法、file_id 是否存在,以及資源版本是否衝突。若 commit API 已成功接受請求,但後續背景流程(例如 consumer、parse、split、indexing)失敗,錯誤不一定會直接由本 API response 回傳。此時建議改查 GET /v1/filesets/{fileset_id}、GET /v1/filesets/{fileset_id}/files、GET /v1/files/{file_id},並搭配檢查 state、fail_reason、fail_detail。

3.14 /v1/filesets/{fileset_id}/duplicate(POST)​

項目內容
Endpoint/v1/filesets/{fileset_id}/duplicate
MethodPOST
常見錯誤代碼AUTH_001、AUTH_002、FILESET_001、FILESET_002、FILE_009
錯誤情境驗證相關問題;原始 Fileset 不存在;新的 Fileset ID 衝突;Files 不存在
補充說明若複製來源 Fileset 本身不存在,或其所關聯的檔案資料異常,就可能發生此類錯誤。

3.15 /v1/models(GET)​

項目內容
Endpoint/v1/models
MethodGET
常見錯誤代碼AUTH_001、AUTH_002、MODEL_001
錯誤情境驗證相關問題;模型服務或 LiteLLM 通訊異常(若系統實作有啟用此錯誤碼)
補充說明通常此 API 錯誤較少,若發生非驗證問題,多半與模型後端服務連線狀態有關。

3.16 /v1/prompts(POST)​

項目內容
Endpoint/v1/prompts
MethodPOST
常見錯誤代碼AUTH_001、AUTH_002、PROMPT_002
錯誤情境驗證相關問題;Prompt ID 已存在
補充說明若建立時使用了已存在的 Prompt ID,系統會拒絕建立。

3.17 /v1/prompts(GET)​

項目內容
Endpoint/v1/prompts
MethodGET
常見錯誤代碼AUTH_001、AUTH_002、VAL_001、VAL_002
錯誤情境驗證相關問題;同時提供 before 與 after;before 或 after 所指定的 cursor id 不存在
補充說明主要與分頁查詢參數有關。

3.18 /v1/prompts/{prompt_id}(GET)​

項目內容
Endpoint/v1/prompts/{prompt_id}
MethodGET
常見錯誤代碼AUTH_001、AUTH_002、PROMPT_001
錯誤情境驗證相關問題;Prompt 不存在
補充說明若指定 Prompt 不存在,查詢會失敗。

3.19 /v1/prompts/{prompt_id}(DELETE)​

項目內容
Endpoint/v1/prompts/{prompt_id}
MethodDELETE
常見錯誤代碼AUTH_001、AUTH_002、PROMPT_001
錯誤情境驗證相關問題;Prompt 不存在
補充說明若指定 Prompt 不存在,刪除會失敗。

3.20 /v1/prompts/{prompt_id}/optimize/auto(POST)​

項目內容
Endpoint/v1/prompts/{prompt_id}/optimize/auto
MethodPOST
常見錯誤代碼AUTH_001、AUTH_002、PROMPT_001
錯誤情境驗證相關問題;Prompt 不存在
補充說明若指定 Prompt 不存在,自動優化請求無法執行。

3.21 /v1/prompts/{prompt_id}/optimize/instruct(POST)​

項目內容
Endpoint/v1/prompts/{prompt_id}/optimize/instruct
MethodPOST
常見錯誤代碼AUTH_001、AUTH_002、PROMPT_001
錯誤情境驗證相關問題;Prompt 不存在
補充說明若指定 Prompt 不存在,依指示優化請求無法執行。

3.22 /v1/qa/generate(POST)​

項目內容
Endpoint/v1/qa/generate
MethodPOST
常見錯誤代碼AUTH_001、AUTH_002、FILESET_001、FILESET_005、FILE_003、QA_001、QA_002
錯誤情境驗證相關問題;Fileset 不存在;Fileset 內沒有任何檔案;File ID already exists;沒有產生任何 QA pairs;部分檔案產生 QA pairs 失敗
補充說明此 API 與 Fileset 內容品質、檔案是否可正常解析,以及是否有足夠文本內容可生成問答有關。若部分檔案失敗,建議再進一步檢查各檔案狀態與內容品質。

4. 補充說明​

4.1 錯誤代碼分類規則​

錯誤代碼依功能領域分類,格式為:

{CATEGORY}_{NUMBER}

類別說明
AUTH身份驗證相關錯誤
VAL參數驗證相關錯誤
FILE檔案管理相關錯誤
FILESET知識版本管理相關錯誤
QA問答生成相關錯誤
PROMPT提示詞管理相關錯誤
MODEL模型服務相關錯誤

4.2 常見 HTTP Status 對應​

HTTP Status說明
400 Bad Request請求本身不合法
401 Unauthorized缺少授權資訊
403 Forbidden授權失敗或無效
404 Not Found資源不存在
409 Conflict資源狀態衝突或版本衝突
415 Unsupported Media Type不支援的檔案格式
422 Unprocessable Entity參數驗證錯誤
500 Internal Server Error系統內部錯誤

5. 建議閱讀順序​

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

順序建議內容
1先看本頁,確認該 Endpoint 常見會出現哪些錯誤
2再看各分類的「錯誤代碼說明」頁面,理解錯誤碼定義與 payload
3若涉及 Fileset Commit / 背景流程,再查看 Fileset State、Fileset File State、File metadata 中的 fail_reason / fail_detail