錯誤代碼說明-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`
Method	`POST`
常見錯誤代碼	`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`
Method	`GET`
常見錯誤代碼	`AUTH_001`、`AUTH_002`、`VAL_001`、`VAL_002`
錯誤情境	驗證相關問題；同時提供 `before` 與 `after`；`before` 或 `after` 所指定的 cursor id 不存在
補充說明	此 API 主要與分頁參數有關，應避免同時提供互斥的 cursor 參數。

3.3 `/v1/file`（POST）¶

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

3.4 `/v1/file/{file_id}`（GET）¶

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

3.5 `/v1/file/{file_id}`（DELETE）¶

項目	內容
Endpoint	`/v1/file/{file_id}`
Method	`DELETE`
常見錯誤代碼	`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`
Method	`GET`
常見錯誤代碼	`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`
Method	`GET`
常見錯誤代碼	`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}`
Method	`GET`
常見錯誤代碼	`AUTH_001`、`AUTH_002`、`FILESET_001`
錯誤情境	驗證相關問題；Fileset 不存在
補充說明	若查不到 Fileset，請確認 `fileset_id` 是否正確，或該資源是否已被刪除。

3.9 `/v1/filesets/{fileset_id}/files`（GET）¶

項目	內容
Endpoint	`/v1/filesets/{fileset_id}/files`
Method	`GET`
常見錯誤代碼	`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`
Method	`POST`
常見錯誤代碼	`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}`
Method	`PUT`
常見錯誤代碼	`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}`
Method	`DELETE`
常見錯誤代碼	`AUTH_001`、`AUTH_002`、`FILESET_001`
錯誤情境	驗證相關問題；Fileset 不存在
補充說明	若指定的 Fileset 不存在，刪除操作會失敗。

3.13 `/v1/filesets/{fileset_id}/commit`（POST）¶

項目	內容
Endpoint	`/v1/filesets/{fileset_id}/commit`
Method	`POST`
常見錯誤代碼	`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`
Method	`POST`
常見錯誤代碼	`AUTH_001`、`AUTH_002`、`FILESET_001`、`FILESET_002`、`FILE_009`
錯誤情境	驗證相關問題；原始 Fileset 不存在；新的 Fileset ID 衝突；Files 不存在
補充說明	若複製來源 Fileset 本身不存在，或其所關聯的檔案資料異常，就可能發生此類錯誤。

3.15 `/v1/models`（GET）¶

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

3.16 `/v1/prompts`（POST）¶

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

3.17 `/v1/prompts`（GET）¶

項目	內容
Endpoint	`/v1/prompts`
Method	`GET`
常見錯誤代碼	`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}`
Method	`GET`
常見錯誤代碼	`AUTH_001`、`AUTH_002`、`PROMPT_001`
錯誤情境	驗證相關問題；Prompt 不存在
補充說明	若指定 Prompt 不存在，查詢會失敗。

3.19 `/v1/prompts/{prompt_id}`（DELETE）¶

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

3.20 `/v1/prompts/{prompt_id}/optimize/auto`（POST）¶

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

3.21 `/v1/prompts/{prompt_id}/optimize/instruct`（POST）¶

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

3.22 `/v1/qa/generate`（POST）¶

項目	內容
Endpoint	`/v1/qa/generate`
Method	`POST`
常見錯誤代碼	`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`

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

1. 說明目的¶

2. 使用方式¶

3. 各 Endpoint 特定錯誤情境¶

3.1 /v1/chat/completions（POST）¶

3.2 /v1/file（GET）¶

3.3 /v1/file（POST）¶

3.4 /v1/file/{file_id}（GET）¶

3.5 /v1/file/{file_id}（DELETE）¶

3.6 /v1/file/{file_id}/content（GET）¶

3.7 /v1/filesets（GET）¶

3.8 /v1/filesets/{fileset_id}（GET）¶

3.9 /v1/filesets/{fileset_id}/files（GET）¶

3.10 /v1/filesets（POST）¶

3.11 /v1/filesets/{fileset_id}（PUT）¶

3.12 /v1/filesets/{fileset_id}（DELETE）¶

3.13 /v1/filesets/{fileset_id}/commit（POST）¶

3.14 /v1/filesets/{fileset_id}/duplicate（POST）¶

3.15 /v1/models（GET）¶

3.16 /v1/prompts（POST）¶

3.17 /v1/prompts（GET）¶

3.18 /v1/prompts/{prompt_id}（GET）¶

3.19 /v1/prompts/{prompt_id}（DELETE）¶

3.20 /v1/prompts/{prompt_id}/optimize/auto（POST）¶

3.21 /v1/prompts/{prompt_id}/optimize/instruct（POST）¶

3.22 /v1/qa/generate（POST）¶