錯誤代碼說明-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-keys | AUTH_001、AUTH_002 | 缺少 Authorization header;Admin Secret 不正確 | 「錯誤代碼說明-身份驗證類」 |
GET /v1/api-keys | AUTH_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/files | AUTH、VAL_001、VAL_002 | 同時提供 before 與 after;cursor ID 不存在 | 「錯誤代碼說明-傳遞參數驗證類」 |
POST /v1/files | AUTH、FILE_001、FILE_003 | 不支援的檔案格式;指定的 File ID 已存在。另外 metadata 不是合法 JSON 物件,或 instant_parse 格式錯誤時,回傳 422 {"detail": ...} | 「錯誤代碼說明-檔案管理類」 |
GET /v1/files/{file_id} | AUTH、FILE_002 | File 不存在 | 「錯誤代碼說明-檔案管理類」 |
DELETE /v1/files/{file_id} | AUTH、FILE_004、FILE_002 | 檔案仍被 Fileset 使用(回應附帶 fileset_ids),需先從這些 Fileset 移除該檔案或刪除 Fileset;File 不存在 | 「錯誤代碼說明-檔案管理類」 |
POST /v1/files/{file_id}/parse | AUTH、FILE_002 | File 不存在。若同一檔案已在以相同模式解析中,不會回傳錯誤,而是回傳 200 與 File {file_id} is already being parsed | 「錯誤代碼說明-檔案管理類」 |
GET /v1/files/{file_id}/content | AUTH、FILE_002、FILE_007、FILE_008 | File 不存在;file_type=parsed_result 但指定 quality 的解析結果不存在;file_type=chunks 但指定 quality 的 chunks 不存在 | 「錯誤代碼說明-檔案管理類」 |
3.3 知識版本管理
| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
|---|---|---|---|
GET /v1/filesets | AUTH、VAL_001、VAL_002 | 同時提供 before 與 after;cursor ID 不存在 | 「錯誤代碼說明-傳遞參數驗證類」 |
POST /v1/filesets | AUTH、FILESET_002、FILE_009 | Fileset ID 已存在;file_ids 中有不存在的檔案(回應附帶 file_ids) | 「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-檔案管理類」 |
GET /v1/filesets/{fileset_id} | AUTH、FILESET_001 | Fileset 不存在 | 「錯誤代碼說明-知識版本管理類」 |
PUT /v1/filesets/{fileset_id} | AUTH、FILESET_001、FILESET_004、FILE_009、FILESET_007 | Fileset 不存在;狀態為 queued/processing/completed 時嘗試變更 file_ids;file_ids 中有不存在的檔案;同時被其他請求修改(版本衝突) | 「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-檔案管理類」 |
DELETE /v1/filesets/{fileset_id} | AUTH、FILESET_001、FILESET_021 | Fileset 不存在;狀態為 queued 或 processing,無法刪除 | 「錯誤代碼說明-知識版本管理類」 |
GET /v1/filesets/{fileset_id}/files | AUTH、FILESET_001、VAL_001、VAL_002 | Fileset 不存在;同時提供 before 與 after;cursor ID 不存在 | 「錯誤代碼說明-知識版本管理類」、「錯誤代碼說明-傳遞參數驗證類」 |
POST /v1/filesets/{fileset_id}/commit | AUTH、FILESET_001、FILESET_005、FILESET_011、FILESET_003、FILESET_022、FILESET_007 | Fileset 不存在;Fileset 內沒有任何檔案;含不支援的檔案格式;狀態為 queued/processing/completed 或上一次 Commit 仍在執行;上一次 Commit 的取消清理尚未完成;版本衝突 | 「錯誤代碼說明-知識版本管理類」 |
DELETE /v1/filesets/{fileset_id}/commit | AUTH、FILESET_001、FILESET_009 | Fileset 不存在;狀態不是 queued/processing/cancelled(對已取消的 Fileset 重複呼叫會直接成功) | 「錯誤代碼說明-知識版本管理類」 |
POST /v1/filesets/{fileset_id}/duplicate | AUTH、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/generate | AUTH、FILESET_001、FILESET_005、QA_001、QA_003 | Fileset 不存在;Fileset 內沒有任何檔案;所有檔案皆未產生 QA pairs;on_oversize=fail 時檔案內容過大,整批處理中止。部分檔案失敗時回傳 HTTP 400 但 body 為成功結構(QA_002 情境) | 「錯誤代碼說明-問答集生成類」、「錯誤代碼說明-知識版本管理類」 |
3.5 提示詞管理
| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
|---|---|---|---|
GET /v1/prompts | AUTH、VAL_001、VAL_002 | 同時提供 before 與 after;cursor ID 不存在 | 「錯誤代碼說明-傳遞參數驗證類」 |
POST /v1/prompts | AUTH、PROMPT_002 | 指定的 Prompt ID 已存在 | 「錯誤代碼說明-提示詞管理類」 |
GET /v1/prompts/{prompt_id} | AUTH、PROMPT_001 | Prompt 不存在 | 「錯誤代碼說明-提示詞管理類」 |
DELETE /v1/prompts/{prompt_id} | AUTH、PROMPT_001 | Prompt 不存在 | 「錯誤代碼說明-提示詞管理類」 |
POST /v1/prompts/{prompt_id}/optimize/auto | AUTH、PROMPT_001 | 原始 Prompt 不存在。模型服務錯誤時回傳非錯誤代碼格式的回應 | 「錯誤代碼說明-提示詞管理類」 |
POST /v1/prompts/{prompt_id}/optimize/instruct | AUTH、PROMPT_001 | 原始 Prompt 不存在;缺少 current_issue 或 desired_behavior 時為 422 {"detail": [...]}。模型服務錯誤時回傳非錯誤代碼格式的回應 | 「錯誤代碼說明-提示詞管理類」 |
3.6 模型
| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
|---|---|---|---|
GET /v1/models | AUTH | 無法從模型服務取得清單時,沿用模型服務回傳的 HTTP Status,body 為 {"detail": "LiteLLM API error: ..."}(無 error_code) | 「例外狀況處理」 |
3.7 對話與檢索
| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
|---|---|---|---|
POST /v1/chat/completions | AUTH、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_010 | prompt_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/references | AUTH、FILESET_001、FILESET_006、CHAT_001、CHAT_002、CHAT_003 | Fileset 不存在;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/templates | AUTH | 建立時只寫入模板並回傳 201。之後的背景解析若失敗(例如 REPORT_TEMPLATE_005),模板 state 會轉為 failed 並記錄於 fail_detail,可用取得模板 API 查詢 | 「錯誤代碼說明-建立報告模板」 |
GET /beta/report-generation/templates/{template_id} | AUTH、REPORT_TEMPLATE_003、REPORT_TEMPLATE_001 | expand 含不支援的欄位;模板不存在 | 「錯誤代碼說明-建立報告模板」 |
PATCH /beta/report-generation/templates/{template_id} | AUTH、REPORT_TEMPLATE_001、REPORT_TEMPLATE_002 | 模板不存在;模板狀態不是 completed | 「錯誤代碼說明-建立報告模板」 |
POST /beta/report-generation/templates/{template_id}/confirm | AUTH、REPORT_TEMPLATE_001、REPORT_TEMPLATE_002、REPORT_TEMPLATE_004 | 模板不存在;模板狀態不是 pending_confirm;slots 與 jinja_html 內的變數不一致 | 「錯誤代碼說明-建立報告模板」 |
3.9 報告生成(Beta)
| Endpoint | 錯誤代碼 | 錯誤情境 | 對照頁 |
|---|---|---|---|
POST /beta/report-generation/reports | AUTH、REPORT_GENERATION_004 | 以既有的 report id 重新建立,但該 report 狀態不是 failed。草稿生成在背景執行,失敗時 report state 轉為 failed 並記錄於 fail_detail | 「錯誤代碼說明-報告生成」 |
POST /beta/report-generation/reports/{report_id}/confirm | AUTH、REPORT_GENERATION_001、REPORT_GENERATION_004、REPORT_GENERATION_007 | Report 不存在;狀態不是 pending_review 或 failed;草稿為空或沒有章節 | 「錯誤代碼說明-報告生成」 |
DELETE /beta/report-generation/reports/{report_id} | AUTH、REPORT_GENERATION_001 | Report 不存在 | 「錯誤代碼說明-報告生成」 |
GET /beta/report-generation/reports/{report_id} | AUTH、REPORT_GENERATION_006、REPORT_GENERATION_001 | expand 含不支援的欄位;Report 不存在 | 「錯誤代碼說明-報告生成」 |
POST /beta/report-generation/reports/{report_id}/export | AUTH、REPORT_GENERATION_001、REPORT_GENERATION_004、FILE_002 | Report 不存在;狀態不是 completed;先前匯出的檔案已被刪除 | 「錯誤代碼說明-報告生成」、「錯誤代碼說明-檔案管理類」 |
4. 補充說明
4.1 錯誤代碼分類規則
錯誤代碼依功能領域分類,格式為 {CATEGORY}_{NUMBER}:
| 類別 | 說明 | 對照頁 |
|---|---|---|
AUTH | 身份驗證相關錯誤 | 「錯誤代碼說明-身份驗證類」 |
API_KEY | API 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 |