# 錯誤代碼說明-報告生成

:::warning[⚠️]

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

:::

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

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

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

### API 直接回傳的錯誤

| **Error Code** | **HTTP Status** | **Scenario** | **Error Message** | **Inherent Payload** |
| --- | --- | --- | --- | --- |
| `REPORT_GENERATION_001` | 404 | 查詢、刪除、匯出或確認草稿時找不到該報告，或報告不屬於目前的 API Key | Report not found. | "report_id": string |
| `REPORT_GENERATION_004` | 409 | 報告狀態不符合該操作允許的狀態（確認草稿需為 `pending_review` 或 `failed`、匯出需為 `completed`、以既有 `id` 重新執行需為 `failed`） | Report is in {state} state, expected {expected_state}. | "state": string, "expected_state": string |
| `REPORT_GENERATION_006` | 400 | `expand` 帶入不支援的欄位（允許：`template`、`draft`、`rendered_html`） | Invalid expand field(s): {fields}. | "fields": string[] |
| `REPORT_GENERATION_007` | 409 | 確認草稿時，報告的 `draft` 為空或沒有任何章節 | Report draft is empty or missing. | "report_id": string |
| `REPORT_GENERATION_003` | 500 | 更新報告資料失敗（報告已不存在或無法更新），可能發生於確認草稿或匯出報告 | Failed to update report state. | "report_id": string, "state": string |

### 背景流程中的錯誤

下列錯誤發生在草稿生成的背景流程，不會由 API 直接回傳。發生時報告狀態轉為 `failed`，並在 `fail_detail` 新增一筆 `failed_step` 為 `generate_report` 的紀錄。

| **Error Code** | **HTTP Status** | **Scenario** | **Error Message** | **Inherent Payload** |
| --- | --- | --- | --- | --- |
| `REPORT_GENERATION_002` | 500 | 章節整合重試後仍失敗 | Report integration failed. |  |
| `REPORT_GENERATION_003` | 500 | 背景流程更新報告狀態失敗（報告已不存在或無法更新） | Failed to update report state. | "report_id": string, "state": string |
| `REPORT_GENERATION_005` | 500 | 整合時沒有任何 `completed` 且有內容的章節（所有章節皆生成失敗，或撰寫指引沒有章節） | No completed chapters to integrate. |  |

其他錯誤：

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

- Request Body 或參數不符合 Schema（例如缺少 `template`、`report_id` 非合法 UUID、`format` 非 `pdf`）時，會回傳 `422`，詳見「錯誤代碼說明-傳遞參數驗證類」章節。
