# 錯誤代碼說明-建立報告模板

:::warning[⚠️]

**Beta 預覽版**  
Report Generation API 目前位於 `/beta` 路徑下，屬於預覽版功能。錯誤代碼與回應格式可能隨產品迭代調整，APMIC 不保證其向下相容性。

:::

以下為 [建立報告模板](https://privstation-docs.apmic.ai/latest/privai-400/建立報告模板.md) 相關 API（`/beta/report-generation/templates*`）的錯誤代碼。回應格式為：

```json
{
  "error_code": "REPORT_TEMPLATE_002",
  "error_message": "Report template is in completed state, expected pending_confirm. Please refer to the API documentation.",
  "state": "completed",
  "expected_state": "pending_confirm"
}
```

`error_message` 結尾固定附上 `Please refer to the API documentation.`；表格中的 Inherent Payload 欄位會與 `error_code`、`error_message` 並列於回應的頂層。

| **Error Code** | **HTTP Status** | **Scenario** | **Error Message** | **Inherent Payload** |
| --- | --- | --- | --- | --- |
| `REPORT_TEMPLATE_001` | 404 | 查詢、確認或更新模板時找不到該模板，或模板不屬於目前的 API Key | Report template not found. |  |
| `REPORT_TEMPLATE_002` | 409 | 模板狀態不符合該操作允許的狀態（確認模板結構需為 `pending_confirm`、PATCH 需為 `completed`） | Report template is in {state} state, expected {expected_state}. | "state": string, "expected_state": string |
| `REPORT_TEMPLATE_003` | 400 | `expand` 帶入不支援的欄位（允許：`jinja_html`、`slots`、`writing_guidelines`） | Invalid expand field(s): {fields}. | "fields": string[] |
| `REPORT_TEMPLATE_004` | 400 | 確認模板結構時，`slots` 與 `jinja_html` 內的變數不一致（缺少或多餘） | Slots and jinja variables are inconsistent. | "missing_slots": string[], "extra_slots": string[] |
| `REPORT_TEMPLATE_005` | 502 | 模板解析階段將 HTML 轉為 Jinja template 時，LLM 回傳無法解析的結果（僅發生於背景處理，見下方說明） | LLM failed to produce a parsable HTML2Jinja output. | "raw_message": string |

`REPORT_TEMPLATE_005` 發生在建立模板後的背景解析流程，不會由報告模板 API 直接回傳。發生時模板狀態轉為 `failed`，並在 `fail_detail` 新增一筆 `failed_step` 為 `parse_template` 的紀錄。  
其他錯誤：

- 未提供或提供無效的 API Key 時，會回傳 `AUTH_001`、`AUTH_002` 或 `AUTH_003`，詳見「錯誤代碼說明-身份驗證類」章節。

- Request Body 或參數不符合 Schema（例如缺少 `source_file_id`、帶入未定義的欄位）時，會回傳 `422`，詳見「錯誤代碼說明-傳遞參數驗證類」章節。
