# 錯誤代碼說明-Chat

本頁說明 `CHAT_` 開頭的錯誤代碼，適用於 Chat Completions（`/v1/chat/completions`）與資料參考搜尋（`/v1/chat/references`）。

| **Error Code** | **HTTP Status** | **Scenario** | **Error Message** | **Inherent Payload** |
| --- | --- | --- | --- | --- |
| `CHAT_001` | 413 | Query is too long to be processed by the embedding / rerank upstream | Query is too long to be processed. | "query_length": int, "upstream_status": int, "upstream_message": string |
| `CHAT_002` | 502 | Reranker upstream service failed | Failed to process the request. | "upstream_status": int, "upstream_message": string |
| `CHAT_003` | 502 | Embedding upstream service (vector retrieval) failed | Failed to process the request. | "upstream_status": int, "upstream_message": string |
| `CHAT_004` | 415 | The selected model does not support image input, or the uploaded file is not a supported image | The model does not support image input, or the uploaded file is not a supported image. | "upstream_status": int, "upstream_message": string |
| `CHAT_005` | 413 | Too many images for the selected model in a single request | Too many images for the selected model in a single request. | "upstream_status": int, "upstream_message": string |
| `CHAT_006` | 502 | Unclassified upstream or internal failure while producing a chat completion | Failed to process the request. | "upstream_status": int, "upstream_message": string |

#### 回應格式

錯誤回應的 `error_message` 會在上表訊息後加上 ` Please refer to the API documentation.`，Inherent Payload 的欄位直接放在回應的頂層。例如：

```json
{
  "error_code": "CHAT_001",
  "error_message": "Query is too long to be processed. Please refer to the API documentation.",
  "query_length": 120000,
  "upstream_status": 400,
  "upstream_message": "..."
}
```

- `upstream_status`：上游服務回傳的 HTTP 狀態碼；無法取得時不會出現此欄位。

- `upstream_message`：上游服務的錯誤訊息；無法取得時不會出現此欄位。

- `query_length`：本次查詢文字的字元數（僅 `CHAT_001`）。

#### 各錯誤代碼說明

| **Error Code** | **適用端點** | **說明與排查建議** |
| --- | --- | --- |
| `CHAT_001` | `/v1/chat/completions`、`/v1/chat/references` | RAG 檢索時，查詢文字過長，embedding 或 reranker 服務拒絕處理。Chat Completions 以最後一則 `user` 訊息的文字作為查詢；請縮短查詢內容，或將長文改用 `file` 區塊 / ReferenceFile 標籤帶入。 |
| `CHAT_002` | `/v1/chat/completions`、`/v1/chat/references` | RAG 的 rerank 階段失敗。通常為暫時性問題，可稍後重試；持續發生請聯絡系統管理員。 |
| `CHAT_003` | `/v1/chat/completions`、`/v1/chat/references` | RAG 的檢索階段（embedding / 向量檢索）失敗。可稍後重試；持續發生請聯絡系統管理員。 |
| `CHAT_004` | `/v1/chat/completions` | `messages` 含 `image_url` 區塊，但所選模型不支援圖片輸入，或圖片內容無法被模型讀取。請改用支援圖片的模型，或確認圖片格式與 data URL 是否正確。 |
| `CHAT_005` | `/v1/chat/completions` | 單次請求的圖片數量超過所選模型的上限。請減少圖片數量。 |
| `CHAT_006` | `/v1/chat/completions` | 產生回覆時發生無法歸類的上游或內部錯誤，例如指定的 `model` 不存在或模型服務回傳錯誤；串流模式下 MCP server 無法連線也會回傳此錯誤。請參考 `upstream_status` / `upstream_message` 排查。 |

#### 串流（stream）模式

- 在串流開始前發生的錯誤，以一般 HTTP 錯誤回應回傳，格式同上。

- 串流開始後才發生的錯誤，HTTP 狀態維持 200，系統會送出一個帶頂層 `error` 物件的 SSE 事件後以 `data: [DONE]` 結束。`error` 物件包含 `message`、`type`、`code`（皆與 OpenAI SDK 相容）以及 `error_code`、`error_message` 與上表的 Inherent Payload 欄位，詳見 [Chat Completions](https://privstation-docs.apmic.ai/latest/privai-400/chat-completions.md) 的「串流中的錯誤」。

#### 相關錯誤代碼

Chat 相關請求也可能回傳其他類別的錯誤代碼：

- 參數驗證（`VAL_003`、`VAL_004`、`VAL_005`）：見 [錯誤代碼說明-傳遞參數驗證類](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-傳遞參數驗證類.md)

- 知識版本（`FILESET_001`、`FILESET_006`）：見「錯誤代碼說明-知識版本管理類」

- 檔案（`FILE_002`、`FILE_007`、`FILE_010`）：見「錯誤代碼說明-檔案管理類」

- 提示詞（`PROMPT_001`）：見「錯誤代碼說明-提示詞管理類」

- 身份驗證：見「錯誤代碼說明-身份驗證類」
