第一刀：可重試與終態

錯誤分類的第一個維度是對消費者行為的指示：這個錯誤重試有沒有用。可重試（服務暫時失效、限流、鎖衝突）指示消費者退避後重送；終態（參數錯誤、權限拒絕、業務規則拒絕）指示消費者停止重試、走修正或人工路徑。這一刀切錯的代價是雙向的：終態錯誤被標成可重試、消費者的 retry 迴圈空轉壓垮服務；可重試被標成終態、暫時性故障變成使用者眼中的永久失敗。

HTTP status 承擔這一刀的粗分類（4xx 終態、5xx 與 429 可重試、見 11.3 的 status 承諾段）、錯誤 body 承擔細分類。兩層要一致 — body 說可重試、status 給 400、中介層跟 SDK 只看 status、消費者的兩層邏輯就互相矛盾。

格式設計：標準與自訂並存的現實

錯誤格式有現行標準、也有大廠自成一格的成熟先例、兩者的設計目標一致：機器可判讀、人類可理解、格式可演化。

RFC 9457 定義 application/problem+json：type（URI）、title、status、detail、instance 五個核心成員、允許 extension members 且要求 client 忽略不認識的欄位（見 11.C35）。兩個設計值得單獨理解：type 用 URI 而非字串 enum、把錯誤種類的命名空間外部化、跨團隊不撞名；「client MUST ignore unknown extensions」是格式的演化條款 — 服務端可以加欄位而不破壞既有消費者、等同錯誤模型的開放封閉原則。

Stripe 的錯誤物件早於這個標準自成一格、分層思路可以直接借用：type 承擔路由層（哪類錯誤、走哪條處理分支）、code 承擔分支層（細粒度機器碼）、param 加 message 承擔 UI 層（哪個欄位錯、給人看什麼）、三個正交欄位讓消費者各層各取所需（見 11.C36）。這個模型還藏著一個結構訊號：idempotency_error 是四個 type 之一 — 冪等衝突在支付 API 是預期常態、錯誤模型要為它保留一級位置（冪等語意主寫在 11.8）。

選標準還是自訂的判準：新 API 從 RFC 9457 起手、拿到現成的演化條款與工具生態；既有 API 有自訂格式且被大量依賴、遷移本身就是 breaking change、務實做法是把 9457 的兩個設計（type 命名空間化、未知欄位忽略條款）補進自訂格式、而非換格式。

錯誤狀態下的系統行為

錯誤模型的最後一段責任是「錯誤發生時、系統還敢做什麼」。Twilio 2013 年計費事故的教訓落在這：關鍵狀態讀不到、自動扣款卻繼續跑、演變成重複扣款（事故時序與冪等閘門的抽象、主寫在 11.8 的反例段）。落到錯誤模型的通用判準：關鍵狀態讀寫失敗的錯誤處理、預設要往「拒絕服務」收斂、而非「帶著壞狀態繼續」— 錯誤分類表裡要有一類「狀態不可信、停止副作用」、它的處理路徑跟一般 5xx 不同。

常見設計錯誤

• 業務失敗包 200：觀測與重試鏈失真、修法見 11.3 的 status 承諾段。
• 錯誤碼用連續數字：code: 1047 無命名空間、跨服務撞號、grep 不到語意 — 用可讀字串或 URI。
• message 當機器介面：消費者 parse 錯誤訊息文字做分支、訊息改字就是 breaking change — 機器分支一律走 type / code。
• 錯誤格式沒有演化條款：第一版沒宣告「未知欄位忽略」、之後每次加欄位都無法確認安全性 — 條款從第一版就寫進文件。

爭論地圖與下一步

本章的分類與格式判準、以 HTTP transport 承載 status 語意為前提。錯誤格式的跨風格交鋒（RFC 9457、envelope 包裝、GraphQL 的 200-with-errors 慣例）是掛在本章的爭論深度文章 backlog（見 模組頁 章節規劃）— GraphQL 把 transport 層 status 跟業務錯誤解耦的做法、在該文攤開、本章不展開。

• 可重試錯誤的消費端行為設計：11.8 API 層冪等設計、6.12 冪等與重放驗證
• 限流錯誤（429）的完整語意：11.9 對外流量語意
• 案例原文：模組十一案例庫

觀察

RFC 9457（IETF Proposed Standard、Standards Track、2023-07）定義 application/problem+json：五個核心成員 type（URI、預設 about:blank）、title、status、detail、instance；允許 extension members 且要求 client 忽略不認識的欄位；建立 IANA common problem types registry（7807 沒有）。RFC 明言 problem details 是補充 HTTP status code、不是取代。

判讀

type 用 URI 而非字串 enum、把錯誤種類的命名空間外部化、避免各團隊 code 撞名；「client MUST ignore unknown extensions」是向前相容的演化條款、等同錯誤模型的 OCP。registry 的新增是對 7807 生態碎片化的直接回應。

對應大綱

11.4 錯誤模型設計（anchor）、錯誤格式爭論文章。

下一步路由

回 模組十一案例庫。

引用源

• RFC 9457: Problem Details for HTTP APIs（IETF、2023）

觀察

Stripe 錯誤物件分四個 type（api_error / card_error / idempotency_error / invalid_request_error）；code 是細粒度機器碼、decline_code 透傳發卡行原因、param 指出出錯欄位、message 明示可直接顯示給終端使用者、附 doc_url 與 request_log_url。HTTP 402 專用於「參數合法但交易被拒」。

判讀

「路由層（type）、分支層（code）、UI 層（param + message）」做成三個正交欄位、client 端 error handling 各層各取所需。idempotency_error 列為 first-class type、顯示冪等衝突在支付 API 是預期常態、不是邊角。Stripe 早於 RFC 7807 生態自成一格 — 標準與自訂並存是錯誤格式爭論的現實背景。

對應大綱

11.4 錯誤模型設計（anchor）、11.8 API 層冪等交叉、錯誤格式爭論文章。

下一步路由

回 模組十一案例庫。

引用源

• Errors（Stripe API reference）