status 語意的粗承諾在 11.3、錯誤格式設計在 11.4、限流語意在 11.9 —— 本章不重述這三章的 producer 側設計、收的是它們共同缺的另一半：consumer 端拿到之後怎麼辦、以及兩端對彼此的期望怎麼寫進契約。

兩端各自期望什麼

consumer 對錯誤回應的期望收斂成四件：可判讀的行為指示（這個錯誤重試有沒有用、要等多久 —— 對應 11.4 的第一刀「可重試與終態」分類、11.9 的 Retry-After）；可分支的機器碼（程式能走 switch、不用 parse 人類訊息 —— 對應 11.4 的 type/code 層）；可自助的 debug 入口（error 帶 request-id 或 trace id、回報時引用它就能被定位）；穩定性（錯誤格式與語意的變更跟正常回應一樣是 breaking change、對應 11.6）。

provider 對 consumer 的期望同樣具體：守 retry 紀律（退避間隔加隨機抖動、有上限、對過載退讓）；快速 ack（多快看 vendor 明文、如 GitHub 的 10 秒、Slack 的 3 秒）、把慢邏輯移出回應路徑；用 event id 去重、不依賴投遞順序（webhook 場景、見 realtime 流派層）；把機器分支寫在 type/code 上、不 parse message 文字 —— consumer 把人類可讀欄位當契約、之後 provider 改個錯字都變 breaking change（Hyrum’s Law（一切可觀察行為終將被依賴）的錯誤版、案例見 11.C75 的 message 穩定性條款）。

這兩張清單合起來是本章的骨架：契約寫得好、兩張清單都成立；寫得偏、一邊的成本變成另一邊的日常。

成本外部化的判讀訊號

單邊設計的產物有固定形態、兩個方向都有。provider 側轉嫁：業務失敗包 200（把「讀 body 才知道成敗」的解析成本推給 consumer、順便讓自己的錯誤率圖表失真、見 11.3 判讀訊號）；不給機器可讀 code（分支成本推給 consumer 去 parse message）；不給 request-id（debug 成本推給 consumer 與自己的 support 團隊）；用兩種 status 表達同一件事且不明文劃分時機（GitHub 超限回 403 或 429、consumer 分支邏輯雙倍、見 11.C43、語意判準主寫在 11.9）；完全不重試的 webhook（重試責任整包轉給 consumer 自建排程、見 11.C61）。最後一項要再切一刀：GitHub 把不重試寫進文件、附補投 API 與投遞狀態查詢 —— 明文轉移是可規劃的契約條款、跟默默轉嫁（不明說、consumer 事後才發現）是兩回事；判讀的重點在「對方知不知道自己接了這筆成本」、不在成本移動本身。

consumer 側轉嫁：盲目 retry 把恢復成本推回 provider —— 失敗源於過載時、retry 是持續攻擊（AWS 內部元件把錯誤率推到 55% 的實例、見 11.C70；retry 行為常繼承自 SDK 預設而非顯式選擇、審自己依賴堆疊的預設值也是 consumer 的義務）；多層各自 retry、三層各三次在底層疊成 64 次嘗試（見 11.C69）；parse message 文字做分支、把自己的穩定性押在 provider 不改字上。

判讀方法：看到任何一項、先問成本被推到哪一端、再回對應的深度文章找修法。

深度議題分流

雙向契約的複雜度集中在幾個議題、各有一篇深度文章：

status 裝不下的東西。單一 status 有三種表達力邊界：裝不下多個結果（部分成功）、裝不下時間軸（202 之後才失敗）、裝不下不確定性（504 分不出「沒送到」還是「執行了」）。兩條處理路線 —— 把狀態表下放 body、或收窄語意保持單一 status 恆為真 —— 在 status 表達力邊界 攤開。

收到錯誤之後重不重試。這是 consumer 最頻繁的決策、也是雙向責任最典型的場景：單一請求層看 status 加冪等合判、集體層要 backoff 加 jitter 防同步波、架構層要決定 retry 放哪一層、配 retry budget 與 circuit breaker。完整判準在 接收方的重試決策。

錯誤跨服務怎麼傳。A 呼叫 B、B 呼叫 C、C 掛了 —— B 同時是 consumer 跟 provider、要決定透傳還是轉譯、以及錯誤細節暴露多少（機器可讀 vs 攻擊偵察面的張力）。在 錯誤傳播與信任邊界。

收到錯誤之後怎麼溝通。consumer 拿 request-id 或 trace id 回報、provider 承諾用它定位 —— 這條回饋迴路是雙向 debug 契約、也是地位不對等最常見的缺口（不給 id、consumer 只能用「大概幾點、大概什麼操作」描述問題）。在 錯誤回報的回饋迴路。

下一步路由

• 錯誤格式的 producer 側設計：11.4 錯誤模型設計
• status 承諾的地基：11.3 資源建模與操作語意
• 429 與配額語意：11.9 對外流量語意
• 重送安全的冪等機制：11.8 API 層冪等設計
• 同一批診斷欄位的觀測動機：4.19 Debuggability by Design
• 案例原文：模組十一案例庫

裝不下多個結果：部分成功的兩條路線

批次操作 5 筆裡 3 成功 2 失敗、一個 status 表達不了。規範與大廠給了方向相反的兩條路線、對照著讀最清楚。

WebDAV 的 207 Multi-Status 是「下放」路線：頂層回 207、每個資源的真實狀態放進 body 的 multistatus 結構、規範明文接收方「needs to consult the contents of the multistatus response body」、207 可以同時用在全成功、部分成功、全失敗（見 11.C64）。這條路線換到表達力、代價由 consumer 端整條鏈承擔：generic client 與中介層（retry、快取、監控）只看 status line、207 對它們一律是成功 —— 部分失敗只有讀得懂 body schema 的 client 看得到、監控圖表上這批半失敗的請求全是綠的。業界更常見的下放形態其實是 200 加 per-item errors（Elasticsearch 的 bulk API、GraphQL 的 errors 欄位都是這條路）：中介層盲化問題與 207 同構、而且連 207 那個「非常規 status」的警示訊號都沒有。

Google AIP 是「收窄」路線、而且立場寫得很硬：AIP-193 明文「APIs should not support partial errors」—— 部分錯誤把錯誤碼搬進 response body、consumer 就得寫專用錯誤處理、通用機制全部失效（見 11.C65）。批次方法的配套規則是一條原子性階梯：同步批次必須原子（全成或全敗、讓單一 status 恆為真；唯讀批次更直接禁止部分成功）；寫入批次要部分成功、必須升級成非同步 operation、失敗明細結構化進 metadata 的 failed_requests map、且 request 要帶 return_partial_success 讓 consumer 顯式 opt-in。

兩條路線的差異正是雙向契約的分野：207 把解析責任默默推給 consumer（收到的人自己發現要讀 body）；AIP 把同一份責任變成顯式同意（consumer 用 opt-in flag 聲明「我會處理部分失敗」、provider 才回部分成功）。設計判準由此而來 —— 部分成功的設計題是「consumer 有沒有明知道自己要處理它」、能不能做反而其次；讓中介層誤判的表達方式（200 或 207 包部分失敗、但消費端沒有 opt-in）是把成本外部化的形態。

裝不下時間軸：202 之後才失敗

202 Accepted 的規範定位是刻意不承諾。RFC 9110 原文：「The 202 response is intentionally noncommittal」、且「There is no facility in HTTP for re-sending a status code from an asynchronous operation」（見 11.C66）—— 一旦回了 202、HTTP 協定不再提供任何管道通知最終失敗。status 只描述「收到當下」、描述不了「之後會不會成」。

責任移轉因此是 202 的內建性質、兩端都要有對應動作。provider 端：202 的回應要指向一個 status monitor（規範用「ought to」、實務上是 Operation resource —— 可輪詢的長時操作資源、設計見 11.C44 AIP-151 與 11.7 的長時操作段）—— 只回 202 不給查詢入口、等於把「結果去哪了」變成 consumer 的問題。consumer 端：把 202 當終局成功、最終失敗就靜默消失 —— 拿到 202 的正確做法是記下 operation 入口、把「確認終局」排進自己的流程。同一個時間軸問題在 webhook 方向更隱蔽：先回 2xx ack、背景處理才失敗 —— ack 的是「收到」、不是「處理成功」、對帳兜底因此是 consumer 的常備件（見 webhook 對外承諾）。

裝不下不確定性：502/504 的 retry 歧義

RFC 9110 對 502 與 504 的定義只描述 gateway 自己的觀察：收到無效回應（502）、沒收到及時回應（504）—— 規範沒有任何欄位區分「上游根本沒收到請求」與「上游執行了、只是回應沒回來」（見 11.C67）。

這個缺口的工程後果（此為從定義出發的推導、非 spec 明文）：connect timeout（請求沒送到、重送安全）跟 read timeout（請求已執行、重送非冪等操作會重複執行）在 consumer 端拿到同一個 504、而兩者的 retry 安全性相反。status 在這裡不是裝不下多個結果、是裝不下「連 gateway 自己都不知道」的不確定性 —— 補強手段全在 status 之外：操作設計成冪等、或帶 idempotency key 讓重送安全（11.8 主寫）、上游做去重。consumer 收到 502/504 的判讀規則因此很短：不確定上游做了沒、就當作做了 —— 除非操作冪等或帶了 key、否則重送前先查。

三種邊界的共同判準

三種邊界指向同一條設計原則：status 是給整條鏈看的最低契約、它裝不下的資訊要嘛收窄語意讓它恆為真（原子批次）、要嘛在 status 之外建立顯式的補充通道（operation resource、opt-in 的部分失敗結構、idempotency key）—— 而不是把資訊藏進只有一方讀得懂的地方、讓另一端與中介層在不知情下做錯決策。

下一步路由

• 雙向契約的框架：11.11 Status 與錯誤的雙向契約
• 拿到模糊 status 之後的重試合判：接收方的重試決策
• 錯誤細節住在哪個容器、以及那個選擇讓誰讀不到錯誤：錯誤格式之爭（本文問的是 status 這一格裝不裝得下事實，該文問的是細節住哪裡）
• 重送安全的機制：11.8 API 層冪等設計
• 長時操作的查詢入口：11.7 集合介面設計
• 案例原文：模組十一案例庫

單一請求層：status、method、冪等的合判

「該不該重試」是三個輸入的合判、status 只是其中之一。status 給第一刀：4xx 終態停止重試、5xx 與 429 可重試（分類判準見 11.4、429 的等待語意見 11.9）。method 與冪等給第二刀：可重試的 status 不等於重送安全 —— GET 與 PUT 有冪等承諾、直接重送；POST 沒有、重送可能重複執行、要嘛操作帶 idempotency key（11.8）、要嘛先查再送。第三刀是不確定性：502/504 分不出上游「沒收到」還是「執行了」、兩種情況 retry 安全性相反（見 11.C67）—— 判讀規則是「不確定就當作做了」、非冪等又沒帶 key 的操作、重送前先查狀態。

這一層的 provider 義務對應存在：用不同的 code 把可重試與不可重試分開（Google SRE Book 的明文建議、見 11.C69）、Retry-After 說到做到（見 11.9）。provider 標示含糊、consumer 的合判就從第一刀開始就錯。

集體層：各自理性、集體災難

單一 consumer 的合理重試、乘上所有 consumer 就變質。兩個機制疊加：第一是 retry 放大 —— 100 QPS 的失敗、每個都重試一次就變 200 QPS、再放大成 300 QPS、「fewer and fewer requests are able to succeed on their first attempt」（SRE Book 原文、見 C69）；第二是同步波 —— 所有 client 用相同的 exponential backoff、退避後會在同一時刻一起回來、每一波都是對 provider 的同步衝擊。

去同步是 consumer 的集體契約責任。Marc Brooker 的實測給了量化根據（模擬情境是 OCC（樂觀並發控制）寫入競爭、非 HTTP retry、結論可遷移）：N 個 client 競爭時總工作量隨 N² 成長、無 jitter 的純 exponential backoff 是「the clear loser」、100 個競爭 client 下加 jitter 讓呼叫量減半以上、Full Jitter（sleep = random(0, min(cap, base * 2^attempt))）總工作量最少（見 11.C68）。判準很直接：backoff 解決「等多久」、jitter 解決「別一起回來」—— 兩者都是 consumer 對 provider 的義務、不是可選優化。

放大失控的終點是 retry 風暴。AWS 官方定義：「the network can quickly become saturated with new and retried requests… This can result in a retry storm」（見 11.C72）。代表案例是 DynamoDB 2015 事故：metadata 服務過載後、逾時的 storage server 自我下線再重試、錯誤率推到 55%、且風暴成形後系統不自癒 —— 復原靠人工暫停請求讓 provider 喘息（見 11.C70）。這個案例的 consumer 是 AWS 自己的內部元件：retry 變攻擊是任何 caller 的結構性行為、不是外部用戶不守規矩。

架構層：retry 放哪一層、配多少預算

多層服務各自 retry 會疊乘：三層各重試 3 次、最底層收到 64 次嘗試（SRE Book、見 C69）。盤點層數時要把 infra 層的隱形 retry 算進去 —— service mesh 的預設 retry policy、SDK 內建的重試（AWS SDK 預設就會重試）都是最常被漏算的一層。retry 因此是要在架構層分配的預算、不是每層的預設行為 —— AWS 的分層建議：低層服務 retry 上限 0 到 1 次、把重試委派給上層（見 C72）、收斂的方向通常是最接近業務語意的外層（它才知道這個操作值不值得再試）；SRE Book 的程序級預算：per-request 上限之外、再設 server-wide retry budget（例如每程序每分鐘 60 次）—— 預算耗盡就不再重試、把「retry 是否過量」從逐請求的局部判斷變成程序級的資源帳。這一層還有一個更上游的預算是剩餘時間：deadline 傳播下、剩的時間不夠跑完一次重試、retry 是純浪費 —— 重不重試之前先看還剩多久；hedged request、adaptive retry 這類進階形態同屬這層的預算分配問題、本文不展開。

circuit breaker 是這一層的閘門、也是 retry 敘事的另一面。Slack 2021 事故給了平衡的實例：網路層恢復後、「plus retries and circuit breaking — got us back to serving」—— retry 加斷路器正是把系統拉回服務狀態的工具（見 11.C71）。判讀：consumer 的 retry 是否有害、取決於 provider 當下在「過載中」還是「恢復中」、而 consumer 無法直接觀測這件事 —— circuit breaker 用本地錯誤率推斷代替猜測：斷路時擋住無效重試保護對方、半開時少量探測驗證恢復、恢復後 retry 轉為復原工具。這兩層的 provider 鏡像義務是給出可推斷的訊號：過載時回明確的 429 加等待時間（而非含糊的 5xx、見 11.9）、提供 health endpoint 或 status page 讓斷路器的推斷有依據 —— consumer 的預算與閘門、要有 provider 的訊號才調得準。

責任分配表

表是索引、每格的成立條件在上文各段。三層合起來的判讀是：重試的每一層都是雙向的 —— consumer 單方面努力擋不住 provider 標示含糊、provider 單方面標清楚也擋不住 consumer 無預算地重送。

下一步路由

• 雙向契約的框架：11.11 Status 與錯誤的雙向契約
• 重送安全的機制設計：11.8 API 層冪等設計
• 429 與退讓訊號：11.9 對外流量語意
• 服務端的過載防護：06 可靠性、circuit breaker 知識卡、retry budget 知識卡
• 帶了 key 之後重送拿到什麼，各家條款不同：Idempotency key 標準化之爭（replay 回首次快照還是最新狀態、認不認得出是重放、保存期多長，直接決定重試窗口能設多寬）
• 案例原文：模組十一案例庫

錯誤契約有保證層與選配層、傳播能力不同

gRPC 的兩層錯誤模型把這件事講得最清楚：標準模型（status code 加 optional message）是所有語言 client 都拿得到的保證層；richer error model（google.rpc.Status 帶結構化 detail）是選配層 —— 官方自列它的三個傳播風險：語言支援不全、payload 撞 header 上限、以及最關鍵的一條：detail 走 trailing metadata（trailer 在回應串流結束後才送出、多數中介層只讀開頭的 header）、proxy 與 logger 看不到（見 11.C73）。

工程含義：錯誤資訊的可見範圍分層 —— status code 全鏈可見（每一跳、每個中介層都讀得到）、結構化 detail 只有端點可見（中間節點對它是盲的）。設計錯誤契約時要按這個分層放資訊：中介層要用的（可不可重試、要不要熔斷）必須放在全鏈可見層、放進 detail 就等於對整條鏈的基礎設施隱形。HTTP 系的對應是 status 全鏈可見、body 端到端 —— 同構的分層、同樣的設計判準。

收到的錯誤能信多少：產生者歧義

中間服務轉譯錯誤前、先要判斷收到的錯誤是誰說的。gRPC 的 status codes 文件給了一手根據：17 個 code 裡只有 7 個（INVALID_ARGUMENT、NOT_FOUND、ALREADY_EXISTS、FAILED_PRECONDITION、ABORTED、OUT_OF_RANGE、DATA_LOSS）保證來自 server 應用邏輯、library 從不自產；UNAVAILABLE、DEADLINE_EXCEEDED、INTERNAL 則可能是中間 channel 或 library 產生 —— consumer 單看 code 分不出來（見 11.C74）。

這對轉譯的含義（推導、標明）：錯誤的可信度不均質。收到「保證來自應用」的 code、語意可以直接轉譯（NOT_FOUND 就是資源不在）；收到產生者不明的 code、轉譯往「暫時性」收斂 —— 回自己的 UNAVAILABLE 或 502 並標可重試、不映射成上游的業務錯誤；要保留產生者線索、放進結構化 detail 而非原樣透傳。它可能只是網路層的一次抖動、不代表上游的業務判斷。中間服務原樣透傳 UNKNOWN 或 INTERNAL、等於把「產生者是誰」的資訊消滅掉、下游拿到的錯誤比你拿到的更不可判讀 —— 資訊只會在鏈上遞減、不會自己恢復。

轉譯的責任：對上游是誰的錯、對下游要換語意

中間服務回給下游的錯誤、語意主詞要換。C 掛了、對 B 是「我的依賴壞了」；但 B 回給 A 的錯誤要回答的是 A 的問題 ——「我的請求怎麼了」。判準（推導）：上游的 5xx 到你這裡、對下游是你的 502/503（你的服務暫時無法完成、可重試）、不是把 C 的 500 連 body 一起倒出去；上游的 4xx 要分辨 —— 是你組請求組錯了（你的 bug、對下游是你的 500）、還是下游的輸入真的非法（對下游還是 4xx、但錯誤內容要換成下游看得懂的欄位名與語彙）。原樣透傳最誘人的時刻是趕工期、它把三種成本外部化：下游拿到不知所云的錯誤（解析成本）、上游的內部細節穿透兩層信任邊界（安全成本）、除錯時分不清錯誤源頭（定位成本）。把轉譯責任制度化的常見做法是收斂到專職層 —— BFF 或 gateway 統一做錯誤轉譯、個別服務只處理自己直接依賴的錯誤（gateway 的執行面屬 05 部署平台）。

暴露多少：機器可讀與偵察面的對撞

錯誤內容該多詳細、有兩股方向相反的一手規範、對撞出中間路線。安全端要求少暴露：OWASP 的規則是非預期錯誤回 generic response、細節只留 server side log —— stack trace 洩漏框架版本、SQL error 幫攻擊者找 injection point、錯誤訊息是攻擊者的偵察面（見 11.C77、攻擊面思路同 07 安全）。可用性端要求夠機器可讀：全 generic 的錯誤讓 consumer 完全無法自助、每個錯誤都變成 support ticket。

Google 的 API 設計規範 AIP-193 用三層受眾設計走出中間路線（見 11.C75）：機器層給 ErrorInfo 的 (reason, domain)、可程式化分支的穩定識別符 —— 但「error messages must not assume that the user will know anything about its underlying implementation」、識別符用 consumer 的語彙命名、不洩內部結構；開發者層給 message、人類可讀的 debug 訊息、可以變動、定位上不可當 API；使用者層給 LocalizedMessage —— 呈現給終端使用者的文案。三層各給對的受眾、既不是 generic 到無法自助、也不是把內部狀態倒出來。附帶一條反向條款：舊 API 沒給機器可讀欄位的、AIP 要求 message 內容必須穩定 —— consumer 已經在 parse 它、改字就是 breaking change；不給機器層、人類層就會被迫變成契約。

下一步路由

• 雙向契約的框架：11.11 Status 與錯誤的雙向契約
• 錯誤格式的 producer 側設計：11.4 錯誤模型設計
• 回報時的定位鉤子：錯誤回報的回饋迴路
• 錯誤訊息的攻擊面：07 安全與資料保護
• dependency call 的診斷欄位（upstream、response class、circuit state）：4.19 Debuggability by Design
• 案例原文：模組十一案例庫

定位鉤子：request-id 與 trace 的契約

回饋迴路的最小契約是每個錯誤回應帶一個唯一識別符。成熟先例都這麼做：Stripe 在錯誤物件附 request_log_url（直達該次請求的 dashboard 紀錄、見 11.C36）、GitHub 的 webhook 每次投遞帶 X-GitHub-Delivery GUID（見 11.C61）、RFC 9457 的 instance 欄位（識別該次 problem occurrence 的 URI）可承擔類似角色（見 11.C35）。契約的兩半：provider 承諾這個 id 在自己的 log 與 trace 系統裡查得到、且保留得比 consumer 的排錯周期長（多久、寫進文件）；consumer 的義務是把它記進自己的錯誤 log —— 收到錯誤時丟棄 id、回報時就退回「大概幾點」。

id 能定位「單跳」、trace 才能定位「全鏈」。一個請求跨五個服務、provider 的第一層 log 只能看到自己這一跳 —— 要從 consumer 回報的識別符追到深處哪個服務出錯、靠的是 trace context 的傳播義務：W3C Trace Context 規定收到 traceparent header 的服務 MUST 往 outgoing request 傳、trace-id 全鏈不變（見 11.C76）。這條 MUST 是回饋迴路的規範地基 —— 任何一跳斷掉傳播、consumer 手上的 id 就只能追到斷點。同一份規範也內建信任邊界：security boundary 可以 restart trace（provider 不必信外部給的 trace-id）、無效 id MUST ignore —— 對外的 API 通常回自己生成的 request-id 給 consumer、內部用 trace-id 關聯、兩者在 gateway 對接（此對接模式為常見實務、非規範明文）。trace 系統本身的建置屬 04 可觀測性（主流實作生態是 OpenTelemetry）、本文只收契約面：id 要不要給、給了承諾什麼。

同一個錯誤、兩種投影：呈現與回報

錯誤內容要分受眾投影、而且兩種投影的組成幾乎相反。給終端使用者呈現的：友善、可行動、不含技術細節（AIP-193 的 LocalizedMessage 層、見 11.C75）—— 使用者不需要知道是哪個服務的哪類錯誤、需要知道「現在能做什麼」。回報給 provider 的：機器碼（type/code 或 reason/domain）、request-id 或 trace-id、時間戳 —— 全是使用者不需要、定位卻缺一不可的欄位。

實務上最常見的組合是「generic 訊息加識別符」：畫面上顯示友善訊息與一個錯誤編號、使用者回報時唸出編號即可。要標明的邊界：OWASP 的 error handling 指南只要求 generic response 加 server-side log、沒有規範「回傳識別符給使用者」這一段（見 11.C77）—— 這個組合是業界常見實務、識別符部分的規範根據是 Trace Context 與各 vendor 的 request-id 慣例、不是 OWASP。consumer 端的落地判準：錯誤呈現層跟錯誤上報層分開寫 —— 呈現層消費 LocalizedMessage 類欄位、上報層把完整 error 物件（含 id）送進自己的 log 與監控、兩層各取所需、不互相污染。

什麼時候該升級：偶發與持續的判讀

回報值不值得、看錯誤的節奏。consumer 端要能區分三種：偶發（單一請求失敗、retry 成功：分散式系統的日常、記 log 不動作）；持續（同一類錯誤連續出現、retry 無效、circuit breaker 開始跳：該檢查是自己的用法錯還是對方壞了）；異常放大（錯誤率突然跳升 —— 對照 provider 的 status page、確認是不是對方的事故）。這條判讀線的量化工具（錯誤率、SLO、告警閾值）屬 04 可觀測性 的範圍、契約面的要求只有一條：provider 要有一個 consumer 查得到的健康狀態出口（status page 或 health endpoint）—— 沒有它、每個 consumer 在事故時都會打 support 問「是不是你們壞了」、支援量在最糟的時刻放大。

provider 側的鏡像責任：把 consumer 的回報當訊號源。同一個 request-id 被多個 consumer 回報、比監控告警更早指出問題；回報的摩擦越低（id 好找、回報入口明確）、這個訊號源越有效 —— 讓 consumer 好回報、是 provider 給自己買的免費監控。

下一步路由

• 雙向契約的框架：11.11 Status 與錯誤的雙向契約
• 錯誤內容的受眾分層：錯誤傳播與信任邊界
• trace 傳播的機制面：4.3 tracing 與 context link
• error rate 與 SLO 的訊號設計：4.6 SLI 量測與 SLO 訊號設計
• 診斷欄位的觀測動機（本篇契約欄位的另一半）：4.19 Debuggability by Design
• 錯誤格式的欄位設計：11.4 錯誤模型設計
• 案例原文：模組十一案例庫

觀察

RFC 4918 §11.1 定義：「The 207 (Multi-Status) status code provides status for multiple independent operations」。§13 明文：頂層雖回 207、「the recipient needs to consult the contents of the multistatus response body for further information about the success or failure of the method execution. The response MAY be used in success, partial success and also in failure situations.」body 是 XML multistatus root、每個 response 元素帶各自資源的 status。

判讀

207 是規範層對 status line 表達力不足的正面承認 —— 頂層 status 降格為「請去讀 body」的訊號、真正的成功失敗判定移進 payload。兩端張力落在 consumer：generic HTTP client 與中介層（retry、cache、監控）只看 status line、207 對它們一律是「成功」、部分失敗只有讀得懂 body schema 的 client 才看得到。provider 換到了表達力、代價是把解析責任整包轉給 consumer —— 跟 Google AIP 的反向立場（見 C65）形成兩條路線的正面對照。

對應大綱

11.11 status 表達力邊界章「部分成功」段（規範層先例、與 C65 對照）。

下一步路由

回 模組十一案例庫。

引用源

• HTTP Extensions for WebDAV（RFC 4918） — 一手 IETF spec、Proposed Standard。已 WebFetch 驗證、逐字引文另以 rfc-editor 官方 .txt 取回核對。

二手來源與狀態標注

207 是 WebDAV 擴充 status、不在 RFC 9110 核心語意內 —— 一般 REST API 借用 207 等於引入 WebDAV 語意、引用時標明脈絡。

觀察

AIP-193（Errors、Approved）專節明文：「APIs should not support partial errors. Partial errors add significant complexity for users, because they usually sidestep the use of error codes, or move those error codes into the response message, where the user must write specialized error handling logic to address the problem.」出口是 long-running operations：「Methods that require partial errors should use long-running operations, and the method should put partial failure information in the metadata message.」

批次三部曲同構：AIP-231（Batch Get）「The operation must be atomic: it must fail for all resources or succeed for all resources (no partial success)」；AIP-233（Batch Create）與 AIP-234（Batch Update）規定同步批次必須原子、非同步批次才可支援部分成功 —— 且支援時 metadata 必須含 map<int32, google.rpc.Status> failed_requests、request 要有 bool return_partial_success 欄位讓 client 顯式 opt-in。

判讀

這組規則把 status 表達力邊界轉成一條設計階梯：同步呼叫只有一個 status 可回、就把語意收窄到原子（讓單一 status 恆為真）；要部分成功、必須升級到非同步 operation、失敗明細結構化進 metadata、且 client 用 opt-in flag 顯式聲明「我會處理部分失敗」。對照 207 的被動解析（consumer 被迫讀 body）、AIP 把契約變成雙向顯式同意 —— 通知責任的分配寫進了介面形狀。

對應大綱

11.11 status 表達力邊界章「部分成功」段（與 C64 對照的反向立場、原子性階梯）。

下一步路由

回 模組十一案例庫。

引用源

• AIP-193 Errors — Approved。已 WebFetch 驗證。
• AIP-231 Batch methods: Get、AIP-233 Batch methods: Create、AIP-234 Batch methods: Update — 均 Approved。已 WebFetch 驗證。

二手來源與狀態標注

AIP 對 gRPC / protobuf 生態（google.rpc.Status）有預設、引到一般 REST 情境要說明可轉譯性。AIP-231 是唯讀批次所以直接禁止部分成功、233/234 是寫入批次才有非同步分支 —— 引用時不可把三者混寫成同一條規則。

觀察

RFC 9110 §15.3.3（Internet Standard）原文：「The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility in HTTP for re-sending a status code from an asynchronous operation.」以及「The 202 response is intentionally noncommittal.」規範同時建議 202 的回應內容「ought to describe the request’s current status and point to (or embed) a status monitor」。

判讀

「intentionally noncommittal」加「no facility for re-sending a status code」合起來是規範層的責任移轉聲明：一旦回了 202、HTTP 協定本身不再提供任何管道通知最終失敗 —— 通知責任落到應用層（status monitor、polling endpoint、callback）、且規範只用「ought to」要求 provider 提供、consumer 得主動來查。consumer 把 202 當終局成功、最終失敗就靜默消失。這是 status 表達力的時間軸邊界：status 只描述「收到當下」、描述不了「之後會不會成」。

對應大綱

11.11 status 表達力邊界章「非同步 / 延遲失敗」段（與 C65 的 LRO 出口、C44 AIP-151 Operation 相互印證）。

下一步路由

回 模組十一案例庫。

引用源

• HTTP Semantics §15.3.3（RFC 9110） — 一手 IETF spec、Internet Standard（STD 97）。

二手來源與狀態標注

RFC 9110 全文超出 WebFetch 摘要視窗、逐字原文以 rfc-editor 官方 .txt 直接取回抽段核對 —— 同源同權威、驗證工具為 curl 非 WebFetch。

觀察

RFC 9110 §15.6.3：「The 502 (Bad Gateway) status code indicates that the server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request.」§15.6.5：「The 504 (Gateway Timeout) status code indicates that the server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete the request.」兩節全文僅此 —— 規範沒有任何欄位區分「上游根本沒收到請求」與「上游收到並執行了、只是回應沒回來或超時」。

判讀

（此段為推導、非 spec 明文。）spec 只定義 gateway 的觀察（沒收到有效或及時回應）、不定義上游的執行狀態。504 尤其如此：connect timeout（請求沒送到、retry 安全）跟 read timeout（請求已執行、對非冪等操作 retry 會重複執行）在 consumer 端拿到同一個 504 —— 兩種情況的 retry 安全性相反、status code 層無法區分。這是 status 表達力的第三種邊界形態：不是裝不下多個結果（C64）、也不是裝不下時間軸（C66）、是裝不下不確定性。緩解手段（idempotency key、上游去重）全在 status code 之外。

對應大綱

11.11 status 表達力邊界章「502/504 歧義」段、接收方重試決策章的 retry 安全合判段（連 11.8 冪等）。

下一步路由

回 模組十一案例庫。

引用源

• HTTP Semantics §15.6.3 / §15.6.5（RFC 9110） — 一手 IETF spec、Internet Standard。

二手來源與狀態標注

逐字原文以 rfc-editor 官方 .txt 取回核對（WebFetch 視窗截斷）。「歧義 → retry 安全性相反」的判讀無單一一手來源明文、正文引用標為從 spec 定義出發的通用推導。

觀察

Marc Brooker 在 AWS Architecture Blog 的實測：N 個 client 同時競爭時「the total amount of work done by the system increases with N²」。三種 jitter 公式逐字：Full Jitter sleep = random(0, min(cap, base * 2^attempt))；Equal Jitter sleep = base*2^attempt/2 + random(0, base*2^attempt/2)；Decorrelated Jitter sleep = min(cap, random(0, last_sleep * 3))。結論：無 jitter 的純 exponential backoff 是「the clear loser」；100 個競爭 client 下 jitter「reduced call count by more than half」；Full Jitter 總工作量最少。

判讀

這篇補上「consumer 各自理性、集體災難」的機制：所有 client 同步 backoff 會形成整齊的 retry 波、每一波都是對 provider 的同步衝擊。jitter 把 consumer 之間的隱性同步打散 —— consumer 的契約責任除了「退讓」（backoff）、還有「彼此去相關」（jitter）、後者是單一 consumer 視角看不到的集體契約。

對應大綱

11.11 接收方重試決策章「backoff 公式選擇」段、retry 風暴的同步波成因。

下一步路由

回 模組十一案例庫。

引用源

• Exponential Backoff And Jitter（AWS Architecture Blog、Marc Brooker） — 一手、作者本人。已 WebFetch 驗證、正文完整取回。

二手來源與狀態標注

發表於 2015、模擬情境是 OCC 寫入競爭而非 HTTP API retry —— 結論可遷移、但引用時說明實驗設定不同。

觀察

Google SRE Book「Addressing Cascading Failures」章：retry 放大例 —— 100 QPS 失敗、retry 疊加成 200 QPS、再 300 QPS、「fewer and fewer requests are able to succeed on their first attempt, so less useful work is being performed」。四條逐字建議：「Always use randomized exponential backoff when scheduling retries」；「Limit retries per request. Don’t retry a given request indefinitely」；「Consider having a server-wide retry budget. For example, only allow 60 retries per minute in a process」；避免「amplifying retries by issuing retries at multiple levels」—— 三層各 retry 3 次會在最底層產生 64 次嘗試。另要求用不同 response code「separate retriable and nonretriable error conditions」。

判讀

這章把責任明確放到兩端：provider 要用 status/error 區分可重試與不可重試（這正是雙向契約的 provider 義務、對應 11.4 的第一刀）；consumer 要有 per-request 上限加全程序 retry budget。跨層疊乘（64 倍）說明 retry 決策必須在架構層指定「哪一層負責 retry」—— 責任沒分配時、每層的局部自保疊成全域攻擊。

對應大綱

11.11 接收方重試決策章「retry budget 量化判準」「retry 放哪一層」段、provider 的 retriable/nonretriable 標示義務（回扣 11.4）。

下一步路由

回 模組十一案例庫。

引用源

• Addressing Cascading Failures（Google SRE Book） — 一手、官方站。已 WebFetch 驗證、正文完整取回。

二手來源與狀態標注

本章未討論 circuit breaker（取回內容確認）—— circuit breaker 段以 C71（Slack）承接。

觀察

AWS 官方 postmortem（Summary of the Amazon DynamoDB Service Disruption、2015-09-20、US-East）：GSI 採用讓 membership 資料膨脹（「a table with large numbers of partitions could have its contribution of partition data to the membership lists quickly double or triple」）。網路擾動後、大量同時的 membership 請求讓 metadata 服務處理變慢並超過時限 —— 逾時的 storage server 自我下線、再重試、進一步壓垮 metadata 服務。「By 2:37am PDT, the error rate … had risen far beyond any level experienced in the last 3 years, finally stabilizing at approximately 55%」。復原手段是 5:06am 主動暫停對 metadata 服務的請求以卸載、加容量、7:10am 恢復。事後修正：加大 metadata 容量、監控 membership 大小、降低 retry 請求速率、metadata 服務分片。

判讀

consumer 的 retry 自保在 provider 過載時等效於 DDoS —— 而這裡的 consumer 是 AWS 自己的 storage server、證明這是結構性行為。風暴一旦成形、系統不會自癒：復原必須人為切斷 retry 迴路（暫停請求）讓 provider 喘息。事後修正同時動兩端 —— provider 加容量加分片、consumer 降 retry 率 —— 責任是雙向的、單邊修不了這類事故。

對應大綱

11.11 接收方重試決策章「retry 風暴實例」段、「風暴成形後為何要人工斷路」。

下一步路由

回 模組十一案例庫。

引用源

• Summary of the Amazon DynamoDB Service Disruption（AWS 官方 postmortem） — 一手。已 WebFetch 驗證、正文完整取回。

二手來源與狀態標注

postmortem 未逐字出現「retry storm」一詞 —— 放大機制從「simultaneous requests + 自我下線再重連」敘述推得、正文引述貼原句、不替 AWS 造詞（「retry storm」的官方定義見 C72）。

觀察

Slack 官方 postmortem（2021-01-04 事故）：誘因是假期後第一個上班日「client caches are cold and clients pull down more data than usual on their first connection」、AWS Transit Gateway 未及時擴容而過載、造成「widespread packet loss」。雪上加霜：CPU 利用率下降「initially triggered some automated downscaling」（最需要容量時反而縮容）；緊急擴容撞到 Linux open files limit 與 AWS quota。復原關鍵句：「This — plus retries and circuit breaking — got us back to serving」、加上 load balancer 的 panic mode；AWS 手動加 TGW 容量後 10:40am 恢復正常。

判讀

retry 的雙面性：底層網路恢復後、正是 retry 加 circuit breaking 讓系統爬回服務狀態。circuit breaker 是 retry 的閘門 —— 斷路時擋住無效重試保護 provider、半開時用少量探測請求驗證恢復、恢復後 retry 才轉為復原工具。責任判讀：consumer 的 retry 是否有害、取決於 provider 當下處於「過載中」還是「恢復中」—— 而 consumer 無法直接觀測這件事、所以需要 circuit breaker 這種本地推斷機制代替猜測。

對應大綱

11.11 接收方重試決策章「circuit breaker 作為 retry 閘門」段、「retry 的雙面性」收束。

下一步路由

回 模組十一案例庫。

引用源

• Slack’s Outage on January 4th 2021（Slack Engineering） — 一手官方 postmortem。已 WebFetch 驗證、正文完整取回。

二手來源與狀態標注

事故主因是網路層（TGW）而非 API 契約層 —— 引用定位為「retry / circuit breaker 在復原期的角色」、不包裝成 API retry 風暴主案例（主案例是 C70）。

觀察

AWS Well-Architected REL05-BP03（Control and limit retry calls）逐字定義：「the network can quickly become saturated with new and retried requests … This can result in a retry storm, which will reduce availability of the service」。分層建議逐字：「For services lower in the stack, a maximum retry limit of zero or one can limit risk yet still be effective as retries are delegated to services higher in the stack」。該文件官方引用 AWS Builders’ Library 的「Timeouts, retries, and backoff with jitter」（Marc Brooker）—— 該文主張 retry 會放大依賴系統的負載、過載時 retry 讓過載更糟、偏好 token bucket 式的本地 retry 限制（意譯、見下方標注）。

判讀

「低層 retry 0-1 次、委派給上層」跟 C69 的跨層疊乘（64 倍）互相印證：retry 是要在架構層分配的預算、不是每層預設行為。token bucket 的本地限制把「retry 是否過量」從每次請求的局部判斷、變成程序級的資源帳 —— consumer 端對 provider 的保護寫成了自己的限流。

對應大綱

11.11 接收方重試決策章「retry 放哪一層」「retry budget」段（與 C69 互證）。

下一步路由

回 模組十一案例庫。

引用源

• REL05-BP03 Control and limit retry calls（AWS Well-Architected） — 一手官方文件。已 WebFetch 驗證、正文完整取回、逐字引文以此為錨。
• Timeouts, retries, and backoff with jitter（AWS Builders’ Library、Marc Brooker） — 一手、但新站為 JS 渲染、WebFetch 僅取得頁殼。

二手來源與狀態標注

Builders’ Library 的措辭（retry 放大、token bucket）為意譯 —— 逐字引文未能取得（JS 渲染）、以 REL05-BP03 的官方引用與逐字定義為錨。正文需要逐字引用時只引 REL05-BP03。

觀察

gRPC 官方 error guide：標準模型是成功回 OK、失敗「gRPC returns one of its error status codes instead, with an optional string error message」。richer error model（google.rpc.Status）「enables servers to return and clients to consume additional error details expressed as one or more protobuf messages」、提供常見錯誤型別（invalid parameters、quota violations、stack traces）、實作上「as trailing metadata in the response」。官方自列三個風險：跨語言實作不一致（僅 C++/Go/Java/Python/Ruby 支援、「broader support remains uncertain」）、proxies 與 loggers 看不到 trailing metadata 裡的 error detail、payload 過大會撞 header size 上限。

判讀

兩端張力在「保證層 vs 選配層」：status code 是所有語言 client 都拿得到的最低契約；richer detail 是選配、而且中間節點（proxy、logger）對它是盲的。中間服務作為 consumer 拿到 richer detail、作為 provider 轉發時不能假設下游也解得開 —— 轉譯責任落在它身上。錯誤契約設計要先分清哪些資訊放保證層（全鏈可見）、哪些放選配層（端到端可見、中間盲）。

對應大綱

11.11 錯誤鏈傳播章「錯誤契約的保證層與選配層」開場、「中間件對錯誤細節的可見性」段。

下一步路由

回 模組十一案例庫。

引用源

• Error handling（gRPC 官方 docs） — 一手、現行版。已 WebFetch 驗證。

二手來源與狀態標注

richer model 語言支援「broader support remains uncertain」—— 不可寫成「gRPC 全語言支援 richer errors」。

觀察

gRPC status codes guide 列 17 個 code、明確標注「Only a subset of the pre-defined status codes are generated by the gRPC libraries」。只由 user code 產生（library 從不產生）的 code：INVALID_ARGUMENT、NOT_FOUND、ALREADY_EXISTS、FAILED_PRECONDITION、ABORTED、OUT_OF_RANGE、DATA_LOSS。UNAVAILABLE 標為「most likely a transient condition, which can be corrected by retrying with a backoff」、但對非冪等操作要小心。

判讀

client 收到 UNAVAILABLE、DEADLINE_EXCEEDED、INTERNAL 時、無法單從 code 分辨是 server 應用回的、還是中間 channel 或 library 自己產生的 —— 只有那 7 個「library 從不產生」的 code 能確定來自 server 邏輯。中間服務轉發錯誤時原樣透傳 UNKNOWN 或 INTERNAL、等於把「產生者是誰」的資訊消滅掉。這直接支撐「provider 暴露多少 vs consumer 能信多少」：錯誤的可信度不是均質的、契約設計要讓 consumer 分得出哪些 code 承載應用語意。

對應大綱

11.11 錯誤鏈傳播章「consumer 對收到的錯誤能信多少」段；UNAVAILABLE 的 retry 判讀連接收方重試決策章。

下一步路由

回 模組十一案例庫。

引用源

• Status codes（gRPC 官方 docs） — 一手、現行版。已 WebFetch 驗證。

觀察

AIP-193（Approved、updated 2024-10-18）規定 error 用 google.rpc.Status（code / message / details）、details 必含 ErrorInfo：reason（[A-Z][A-Z0-9_]+[A-Z0-9]、max 63 字元）、domain（全域唯一、通常是服務名如 pubsub.googleapis.com）、metadata（request-specific key-value）。(reason, domain) 組成機器可讀識別符、同一錯誤必須保持一致。信任邊界原文：「error messages must not assume that the user will know anything about its underlying implementation」。message 定位是「developer-facing, human-readable “debug message”」、給終端使用者的文案走 LocalizedMessage。另有穩定性規則：沒帶 ErrorInfo 的舊 API「The content of Status.message must be stable」—— client 已在 parse message、動了就 break。

判讀

AIP-193 把「provider 暴露多少」拆成三個受眾層：機器（ErrorInfo 的 reason/domain、可程式化分支）、開發者（message、可變動但不可當 API）、終端使用者（LocalizedMessage）。「must not assume underlying implementation」是信任邊界的正面規範 —— 錯誤要用 consumer 的語彙寫、不是把內部狀態倒出來。message 穩定性規則反向揭露 Hyrum’s Law 張力：provider 沒給機器可讀欄位、consumer 就會把人類可讀欄位當契約、之後改字就是 breaking change。

對應大綱

11.11 錯誤鏈傳播章「錯誤契約的三層受眾」「provider 該暴露什麼」段（與 C77 OWASP 對撞成中間路線）。

下一步路由

回 模組十一案例庫。

引用源

• AIP-193 Errors — Approved、updated 2024-10-18。已 WebFetch 驗證（兩次交叉確認）。

二手來源與狀態標注

AIP-193 沒有任何「中間服務怎麼轉譯 upstream 錯誤」的條文（兩次針對性取回確認缺席）—— 它只規範 outbound error 的形狀。「跨服務轉譯」的責任論證是從雙重身分推導、正文標明是推導不是引用。

觀察

W3C Trace Context（Recommendation、2021-11-23）解決的問題原文：「Traces that are collected by different tracing vendors cannot be correlated as there is no shared unique identifier」。traceparent 格式 version-trace-id-parent-id-trace-flags（trace-id 32 hex、parent-id 16 hex、flags 2 hex）。收到 traceparent 的服務 MUST 往 outgoing request 傳、允許的變更只有三種：更新 parent-id、更新 sampled flag、restart trace（在 security boundary 全部重新生成）。tracestate 載 vendor 專屬 key-value、「If the value of the traceparent field wasn’t changed before propagation, tracestate MUST NOT be modified」。無效 id 的處理：trace-id 全零或含非法字元、parent-id 無效時「Vendors MUST ignore the traceparent」。

判讀

consumer 回報問題時附的 trace id 之所以能關聯全鏈、是因為每一跳都有 MUST 級的傳播義務 —— 這是回饋迴路的規範地基。但 spec 同時內建信任邊界的兩個機制：security boundary 可 restart trace（provider 不必信 consumer 給的 trace-id）、無效 id MUST ignore（不把不可信識別符往下游傳播）。中間服務的雙重身分在這裡最具體：對 upstream 是「要不要信 incoming traceparent」的 consumer、對 downstream 是「必須產新 parent-id 再傳」的 provider。

對應大綱

11.11 回饋迴路章「trace id 作為雙向 debug 契約」段；restart-at-boundary 交叉到錯誤鏈傳播章的信任邊界段。

下一步路由

回 模組十一案例庫。

引用源

• Trace Context（W3C Recommendation、2021-11-23） — 一手 W3C 規範。已 WebFetch 驗證。

二手來源與狀態標注

Trace Context Level 2 目前僅 Candidate Recommendation Draft（2024-03-28、自述「should not be cited as final」）—— 引用以 Level 1 Recommendation 為準、Level 2 最多當註腳。

觀察

OWASP Error Handling Cheat Sheet 核心規則：非預期錯誤時「a generic response is returned by the application but the error details are logged server side for investigation, and not returned to the user」。理由是偵察風險：「unhandled errors can assist an attacker in this initial phase」—— 實例包含 stack trace 洩漏 Struts2/Tomcat 版本、SQL error 洩漏安裝路徑並幫攻擊者「identify an injection point」。實作範例是統一回 HTTP 500 加 generic body（如 {"message":"An error occur, please retry"}）。另建議監控 5xx：「a good indication of the application failing for some sets of inputs」。

判讀

OWASP 給了「provider 少暴露」的安全端論證、跟 AIP-193 的「多給機器可讀細節」形成張力的兩端 —— 全 generic 讓 consumer 完全無法自助、全細節變成攻擊偵察面。AIP-193 的 (reason, domain) 設計正是中間路線：給分支用的機器可讀識別符、不洩內部實作。這組對撞是「provider 該暴露什麼」的邊界討論骨架、對應 backend/07 的攻擊面思路。

對應大綱

11.11 錯誤鏈傳播章「暴露的下限：安全邊界」段（與 C75 對照）、連 07 安全。

下一步路由

回 模組十一案例庫。

引用源

• Error Handling Cheat Sheet（OWASP Cheat Sheet Series） — 一手、現行版。已 WebFetch 驗證。

二手來源與狀態標注

該頁完全沒提 error ID / correlation id 回傳給使用者 ——「generic message + 附 trace id 供回報」這個常見組合不能掛 OWASP 出處：trace id 部分引 C76（W3C Trace Context）、組合本身標明是常見實務而非 OWASP 規範。