Error Handling · 錯誤處理設計

---
doc_type: "error-handling"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["api-spec", "sequence-diagram"]
  optional: ["non-functional-reqs", "threat-model"]
---

# Error Handling: <service-name>

**Status:** Draft · **Owner:** <SD/Dev> · **Last updated:** YYYY-MM-DD

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 5 段（編號 1, 2, 3, 9, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每個錯誤碼必答四件事：**retryable 嗎？冪等嗎？要 alert 嗎？client 看得到什麼？** 每條結論行內加 `（依據：api-spec §endpoint / sequence-diagram §failure-path）`；每欄位帶 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造錯誤碼。錯誤回應 body **一律用 RFC 9457（Problem Details）格式**；每條 retry 必含 backoff + jitter + max attempts + idempotency key；**不得輸出 OpenAPI / YAML schema**（那是 api-spec 卡的事）。

---

## 1. Executive Summary

<!-- ai-fill: 3-5 行說明本服務涵蓋哪些 endpoint、錯誤回應採 RFC 9457、主要可重試 / 不可重試錯誤、最高風險（重複扣款 / 洩漏內部錯誤） -->

<3-5 行說明>

> **TL;DR:** <一句話：本服務統一用 RFC 9457，X 類錯誤可重試（含冪等），Y 類不可重試直接回 client>

---

## 2. Error Catalog（錯誤碼目錄）

<!-- ai-rule: 每個對外 endpoint 至少列其可能錯誤碼。retryable? 與 client action 兩欄不可空 -->

| Code | HTTP status | Meaning | Retryable? | Client action | Confidence |
|---|---|---|---|---|---|
| `ORDER_NOT_FOUND` | 404 | 訂單不存在 | no | 顯示「找不到訂單」 | **[H]** |
| `INVENTORY_INSUFFICIENT` | 409 | 庫存不足 | no | 顯示「商品已售完」 | **[H]** |
| `PAYMENT_DECLINED` | 402 | 發卡行拒絕 | no | 提示換卡 | **[H]** |
| `PAYMENT_GATEWAY_TIMEOUT` | 504 | Stripe 逾時 | yes（同 key） | 自動重試，顯示「處理中」 | **[H]** |
| `RATE_LIMITED` | 429 | 超過配額 | yes（依 `Retry-After`） | backoff 後重試 | **[H]** |
| `INTERNAL` | 500 | 未預期錯誤 | no（client 端） | 顯示通用錯誤 + traceId | **[M]** |

---

## 3. Retry & Idempotency（核心）

| Operation | Retryable | Max attempts | Backoff | Idempotency key |
|---|---|---|---|---|
| `POST /v1/orders` | on 504/timeout | 2 | exp + jitter, base 200ms | `Idempotency-Key` header (UUID v4) |
| `Stripe charge` | on timeout/5xx | 3 | exp + jitter, base 500ms | `orderId` |
| `GET /v1/orders/{id}` | on 5xx（讀取安全） | 3 | exp + jitter | n/a（天生冪等） |

> **規則：** retryable 的前提是**冪等**。非冪等寫入沒帶 idempotency key，一律不得自動重試。

---

## 9. Risks

<!-- ai-rule: 至少 3 個（retry storm / 洩漏內部錯誤 / 吞掉例外） -->

> **R1:** <e.g. 504 自動重試但 Stripe 未帶 idempotency key → 重複扣款> — **Mitigation:** 強制以 `orderId` 為 key — **Owner:** <Dev>
>
> **R2:** <e.g. 500 把 DB 錯誤訊息直吐 client → 洩漏 schema> — **Mitigation:** 對外只回 `INTERNAL` + traceId — **Owner:** <SD>
>
> **R3:** <e.g. catch 後 swallow，client 拿到 200 但其實失敗> — **Mitigation:** 禁止空 catch，未知錯誤 map 到 `INTERNAL` — **Owner:** <Dev>

---

## 12. Confidence & Sources & TODO

- **整份文件最低 confidence 欄位：** <列出所有 [L] 與 [M]>
- **Fabricated assumptions（推測但 input 未明說）：**
  - <假設 1：例：假設 Stripe 逾時可安全以 orderId 重試>
- **Highest-value next input:** <下一份最該補的：實測各 endpoint 錯誤率分布 / SRE alert 門檻>

### TODO（缺資料）

- _TODO: 需要 SRE 確認哪些錯誤碼需 page、哪些只進 dashboard_

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 5 段 H2 章節齊全（編號 1, 2, 3, 9, 12，刻意不連號）
> - [ ] 每個錯誤碼都有 retryable flag + client action
> - [ ] 每條 retry 含 backoff + jitter + max attempts + idempotency key
> - [ ] 對外不洩漏 stack trace / PII（internal 錯誤只回通用碼 + traceId）
> - [ ] 錯誤回應 body 用 RFC 9457（Problem Details）
> - [ ] 無 OpenAPI / YAML schema 輸出