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

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

本頁依 API Endpoint 整理 PrivAI 4.0.0 各端點可能回傳的錯誤代碼與觸發情境,作為本章各錯誤代碼分類頁的交叉對照索引。


1. 使用方式​

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

步驟說明
1先確認呼叫的 Endpoint 與 HTTP Method 是否正確(路徑皆為複數,例如 /v1/files、/v1/filesets、/v1/prompts)
2在本頁找到該 Endpoint,對照回應中的 error_code
3依「對照頁」欄位前往對應的錯誤代碼說明頁,查閱該錯誤代碼的 HTTP Status、錯誤訊息與 Inherent Payload
4若回應沒有 error_code(例如 422 {"detail": [...]}),請見 「例外狀況處理」 的「非錯誤代碼格式的回應」
5若為 Fileset Commit 或其他背景流程問題,請改查資源的 state 與 metadata.fail_detail,見 「例外狀況處理」

2. 所有端點共通的錯誤​

錯誤代碼適用範圍對照頁
AUTH_001、AUTH_002、AUTH_003使用 API Key 驗證的所有端點(下表以「AUTH」表示)「錯誤代碼說明-身份驗證類」
AUTH_001、AUTH_002/v1/api-keys 系列端點(使用 Admin Secret 驗證,不會有 AUTH_003)「錯誤代碼說明-身份驗證類」
無POST /v1/mcp/tools/discover 不需要 Authorization header
422 {"detail": [...]}(無 error_code)所有端點:欄位型別、必填、enum、數值範圍或 UUID 格式驗證失敗「例外狀況處理」

3. 各 Endpoint 特定錯誤情境​

3.1 API Key 管理​

Endpoint錯誤代碼錯誤情境對照頁
POST /v1/api-keysAUTH_001、AUTH_002缺少 Authorization header;Admin Secret 不正確「錯誤代碼說明-身份驗證類」
GET /v1/api-keysAUTH_001、AUTH_002、VAL_001、VAL_002驗證相關問題;同時提供 before 與 after;before 或 after 指定的 ID 不存在「錯誤代碼說明-身份驗證類」、「錯誤代碼說明-傳遞參數驗證類」
PATCH /v1/api-keys/{id}(PUT 為已棄用的相容路徑,行為相同)AUTH_001、AUTH_002、API_KEY_001驗證相關問題;指定的 API Key id 不存在「錯誤代碼說明-身份驗證類」

expires_at 必須是 ISO 8601 時間字串,格式錯誤時會得到 422 {"detail": [...]}。

3.2 檔案管理​

Endpoint錯誤代碼錯誤情境對照頁
GET /v1/filesAUTH、VAL_001、VAL_002同時提供 before 與 after;cursor ID 不存在「錯誤代碼說明-傳遞參數驗證類」
POST /v1/filesAUTH、FILE_001、FILE_003不支援的檔案格式;指定的 File ID 已存在。另外 metadata 不是合法 JSON 物件,或 instant_parse 格式錯誤時,回傳 422 {"detail": ...}「錯誤代碼說明-檔案管理類」
GET /v1/files/{file_id}AUTH、FILE_002File 不存在「錯誤代碼說明-檔案管理類」
DELETE /v1/files/{file_id}AUTH、FILE_004、FILE_002檔案仍被 Fileset 使用(回應附帶 fileset_ids),需先從這些 Fileset 移除該檔案或刪除 Fileset;File 不存在「錯誤代碼說明-檔案管理類」
POST /v1/files/{file_id}/parseAUTH、FILE_002File 不存在。若同一檔案已在以相同模式解析中,不會回傳錯誤,而是回傳 200 與 File {file_id} is already being parsed「錯誤代碼說明-檔案管理類」
GET /v1/files/{file_id}/contentAUTH、FILE_002、FILE_007、FILE_008File 不存在;file_type=parsed_result 但指定 quality 的解析結果不存在;file_type=chunks 但指定 quality 的 chunks 不存在「錯誤代碼說明-檔案管理類」

3.3 知識版本管理​

Endpoint錯誤代碼錯誤情境對照頁
GET /v1/filesetsAUTH、VAL_001、VAL_002同時提供 before 與 after;cursor ID 不存在「錯誤代碼說明-傳遞參數驗證類」
POST /v1/filesetsAUTH、FILESET_002、FILE_009Fileset ID 已存在;file_ids 中有不存在的檔案(回應附帶 file_ids)「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-檔案管理類」
GET /v1/filesets/{fileset_id}AUTH、FILESET_001Fileset 不存在「錯誤代碼說明-知識版本管理類」
PUT /v1/filesets/{fileset_id}AUTH、FILESET_001、FILESET_004、FILE_009、FILESET_007Fileset 不存在;狀態為 queued/processing/completed 時嘗試變更 file_ids;file_ids 中有不存在的檔案;同時被其他請求修改(版本衝突)「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-檔案管理類」
DELETE /v1/filesets/{fileset_id}AUTH、FILESET_001、FILESET_021Fileset 不存在;狀態為 queued 或 processing,無法刪除「錯誤代碼說明-知識版本管理類」
GET /v1/filesets/{fileset_id}/filesAUTH、FILESET_001、VAL_001、VAL_002Fileset 不存在;同時提供 before 與 after;cursor ID 不存在「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-傳遞參數驗證類」
POST /v1/filesets/{fileset_id}/commitAUTH、FILESET_001、FILESET_005、FILESET_011、FILESET_003、FILESET_022、FILESET_007Fileset 不存在;Fileset 內沒有任何檔案;含不支援的檔案格式;狀態為 queued/processing/completed 或上一次 Commit 仍在執行;上一次 Commit 的取消清理尚未完成;版本衝突「錯誤代碼說明-知識版本管理類」
DELETE /v1/filesets/{fileset_id}/commitAUTH、FILESET_001、FILESET_009Fileset 不存在;狀態不是 queued/processing/cancelled(對已取消的 Fileset 重複呼叫會直接成功)「錯誤代碼說明-知識版本管理類」
POST /v1/filesets/{fileset_id}/duplicateAUTH、FILESET_001、FILESET_002來源 Fileset 不存在;request body 指定的新 Fileset ID 已存在「錯誤代碼說明-知識版本管理類」

Commit API 成功時回傳 202,之後在背景執行的解析、切塊、Embedding 若失敗,錯誤不會由 Commit API 回傳。請改查 GET /v1/filesets/{fileset_id}、GET /v1/filesets/{fileset_id}/files、GET /v1/files/{file_id},並檢查 state 與 metadata.fail_detail(見 「例外狀況處理」、「Fileset 知識版本建立流程」)。

3.4 問答集生成​

Endpoint錯誤代碼錯誤情境對照頁
POST /v1/qa/generateAUTH、FILESET_001、FILESET_005、QA_001、QA_003Fileset 不存在;Fileset 內沒有任何檔案;所有檔案皆未產生 QA pairs;on_oversize=fail 時檔案內容過大,整批處理中止。部分檔案失敗時回傳 HTTP 400 但 body 為成功結構(QA_002 情境)「錯誤代碼說明-問答集生成類」、「錯誤代碼說明-知識版本管理類」

3.5 提示詞管理​

Endpoint錯誤代碼錯誤情境對照頁
GET /v1/promptsAUTH、VAL_001、VAL_002同時提供 before 與 after;cursor ID 不存在「錯誤代碼說明-傳遞參數驗證類」
POST /v1/promptsAUTH、PROMPT_002指定的 Prompt ID 已存在「錯誤代碼說明-提示詞管理類」
GET /v1/prompts/{prompt_id}AUTH、PROMPT_001Prompt 不存在「錯誤代碼說明-提示詞管理類」
DELETE /v1/prompts/{prompt_id}AUTH、PROMPT_001Prompt 不存在「錯誤代碼說明-提示詞管理類」
POST /v1/prompts/{prompt_id}/optimize/autoAUTH、PROMPT_001原始 Prompt 不存在。模型服務錯誤時回傳非錯誤代碼格式的回應「錯誤代碼說明-提示詞管理類」
POST /v1/prompts/{prompt_id}/optimize/instructAUTH、PROMPT_001原始 Prompt 不存在;缺少 current_issue 或 desired_behavior 時為 422 {"detail": [...]}。模型服務錯誤時回傳非錯誤代碼格式的回應「錯誤代碼說明-提示詞管理類」

3.6 模型​

Endpoint錯誤代碼錯誤情境對照頁
GET /v1/modelsAUTH無法從模型服務取得清單時,沿用模型服務回傳的 HTTP Status,body 為 {"detail": "LiteLLM API error: ..."}(無 error_code)「例外狀況處理」

3.7 對話與檢索​

Endpoint錯誤代碼錯誤情境對照頁
POST /v1/chat/completionsAUTH、VAL_003、VAL_004、VAL_005同時提供 prompt 與 prompt_id;messages 順序不符規則;同時提供 fileset_id 與 fileset_ids「錯誤代碼說明-傳遞參數驗證類」
POST /v1/chat/completions(續)PROMPT_001、FILESET_001、FILESET_006、FILE_002、FILE_007、FILE_010prompt_id 指定的 Prompt 不存在;fileset_ids 中有 Fileset 不存在;有 Fileset 狀態不是 completed/partial_failed;messages 引用的檔案不存在、指定品質的解析結果不存在或內容為空「錯誤代碼說明-提示詞管理類」、「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-檔案管理類」
POST /v1/chat/completions(續)CHAT_001、CHAT_002、CHAT_003、CHAT_004、CHAT_005、CHAT_006查詢內容過長;Reranker 或 Embedding 服務失敗;模型不支援圖片輸入或圖片無法辨識;圖片數量超過模型上限;其他無法歸類的模型服務或內部錯誤(CHAT_006,例如模型服務回傳錯誤)。stream: true 且串流已開始後發生的錯誤,會以 SSE error 事件送出。使用 MCP Tool 但無法連線至 MCP server 時,串流模式回傳 CHAT_006,非串流模式回傳 500(無 error_code)「錯誤代碼說明-Chat」
POST /v1/chat/referencesAUTH、FILESET_001、FILESET_006、CHAT_001、CHAT_002、CHAT_003Fileset 不存在;Fileset 狀態不是 completed/partial_failed;查詢內容過長;Reranker 或 Embedding 服務失敗。缺少 query string 的 fileset_id 或 query、fileset_id 不是合法 UUID,或未送出 Request Body 時,回傳 422 {"detail": [...]}「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-Chat」
POST /v1/mcp/tools/discover無不需驗證。本端點不會回傳 PrivAI 錯誤代碼:authorization 與 headers.Authorization 同時提供等 request body 驗證失敗時回傳 422 {"detail": [...]};無法連線至 MCP server、server_url 不是 http(s) 等執行期失敗一律回傳 500「例外狀況處理」

在多 Filesets 模式下,fileset_ids 中任一 Fileset 不符合條件時整個 request 都會失敗;fileset_ids: [] 不視為錯誤,而是視為未指定 Fileset,不執行 RAG。

3.8 報告模板(Beta)​

Endpoint錯誤代碼錯誤情境對照頁
POST /beta/report-generation/templatesAUTH建立時只寫入模板並回傳 201。之後的背景解析若失敗(例如 REPORT_TEMPLATE_005),模板 state 會轉為 failed 並記錄於 fail_detail,可用取得模板 API 查詢「錯誤代碼說明-建立報告模板」
GET /beta/report-generation/templates/{template_id}AUTH、REPORT_TEMPLATE_003、REPORT_TEMPLATE_001expand 含不支援的欄位;模板不存在「錯誤代碼說明-建立報告模板」
PATCH /beta/report-generation/templates/{template_id}AUTH、REPORT_TEMPLATE_001、REPORT_TEMPLATE_002模板不存在;模板狀態不是 completed「錯誤代碼說明-建立報告模板」
POST /beta/report-generation/templates/{template_id}/confirmAUTH、REPORT_TEMPLATE_001、REPORT_TEMPLATE_002、REPORT_TEMPLATE_004模板不存在;模板狀態不是 pending_confirm;slots 與 jinja_html 內的變數不一致「錯誤代碼說明-建立報告模板」

3.9 報告生成(Beta)​

Endpoint錯誤代碼錯誤情境對照頁
POST /beta/report-generation/reportsAUTH、REPORT_GENERATION_004以既有的 report id 重新建立,但該 report 狀態不是 failed。草稿生成在背景執行,失敗時 report state 轉為 failed 並記錄於 fail_detail「錯誤代碼說明-報告生成」
POST /beta/report-generation/reports/{report_id}/confirmAUTH、REPORT_GENERATION_001、REPORT_GENERATION_004、REPORT_GENERATION_007Report 不存在;狀態不是 pending_review 或 failed;草稿為空或沒有章節「錯誤代碼說明-報告生成」
DELETE /beta/report-generation/reports/{report_id}AUTH、REPORT_GENERATION_001Report 不存在「錯誤代碼說明-報告生成」
GET /beta/report-generation/reports/{report_id}AUTH、REPORT_GENERATION_006、REPORT_GENERATION_001expand 含不支援的欄位;Report 不存在「錯誤代碼說明-報告生成」
POST /beta/report-generation/reports/{report_id}/exportAUTH、REPORT_GENERATION_001、REPORT_GENERATION_004、FILE_002Report 不存在;狀態不是 completed;先前匯出的檔案已被刪除「錯誤代碼說明-報告生成」、「錯誤代碼說明-檔案管理類」

4. 補充說明​

4.1 錯誤代碼分類規則​

錯誤代碼依功能領域分類,格式為 {CATEGORY}_{NUMBER}:

類別說明對照頁
AUTH身份驗證相關錯誤「錯誤代碼說明-身份驗證類」
API_KEYAPI Key 管理相關錯誤(與身份驗證的 AUTH 類錯誤分開)「錯誤代碼說明-身份驗證類」
VAL參數驗證相關錯誤「錯誤代碼說明-傳遞參數驗證類」
FILE檔案管理相關錯誤「錯誤代碼說明-檔案管理類」
FILESET知識版本管理相關錯誤「錯誤代碼說明-知識版本管理類」
PROMPT提示詞管理相關錯誤「錯誤代碼說明-提示詞管理類」
QA問答集生成相關錯誤「錯誤代碼說明-問答集生成類」
CHAT對話、檢索與上游模型服務相關錯誤「錯誤代碼說明-Chat」
REPORT_TEMPLATE報告模板相關錯誤「錯誤代碼說明-建立報告模板」
REPORT_GENERATION報告生成相關錯誤「錯誤代碼說明-報告生成」

4.2 常見 HTTP Status 對應​

HTTP Status說明
400 Bad Request請求本身不合法,或資源內容不允許該操作(例如 Fileset 沒有檔案)
401 Unauthorized缺少授權資訊
403 Forbidden授權無效或 API Key 已過期
404 Not Found資源不存在
409 Conflict資源狀態衝突、ID 重複或版本衝突
413 Content Too Large查詢內容過長,或圖片數量超過模型上限
415 Unsupported Media Type不支援的檔案格式,或模型不支援圖片輸入
422 Unprocessable Entity參數驗證錯誤
500 Internal Server Error系統內部錯誤
502 Bad Gateway上游服務(模型、Embedding、Reranker)處理失敗

5. 建議閱讀順序​

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

順序建議內容
1「例外狀況處理」:了解錯誤回應格式與背景流程錯誤的查詢方式
2本頁:確認該 Endpoint 可能出現哪些錯誤
3各分類的「錯誤代碼說明」頁面:理解錯誤代碼定義與 Inherent Payload
4若涉及 Fileset Commit/背景流程,再查看 「File Parse State、Fileset File State 與 Fileset State 的差異」 與檔案的 metadata.fail_detail