錯誤・限流・重試・冪等

每個回應都有 x-request-id

成功與失敗都有。它是：

• 你回報問題時必附的查詢鍵；
• 平台計量的 idempotency key——所以同一個請求重試不會被重複計量。

把它記進你的 log，對照你自己的 trace id。

錯誤形狀

所有錯誤共用一個極簡的 problem 物件（application/problem+json）：

{
  "error": "revision_conflict",
  "message": "the resource was modified; re-read and retry",
  "requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh6p"
}

• error 是穩定的機器可讀代碼。程式判斷請用它。
• message 是給人看的，隨時可能改字，不要拿它做判斷。它也刻意不含「資源是否存在」的線索、內部路徑或任何秘密。

穩定代碼清單

下表由契約產生：Problem.error 是封閉集合，Gateway 內部與下游的錯誤碼是它的 超集，會被折成這些公開代碼，不外流。

ℹ️ delegated 與 shared profile 的 token 不在這裡被擋：它們的簽章 是對的，會走完驗證再由授權決定拒絕，所以拿到的是 403 profile_not_supported。

⚠️ tenant_mismatch 與 no_relationship 打在 person 資源上時會變成 404， 不是 403——否則 403 與 404 的差別本身就是一支「這個 person 存不存在」的 探測器（ADR-004 D9）。不透露資源是否存在是刻意的。

ℹ️ tenant_suspended 不折成 404，即使打在 person 資源上也一樣回 403。 它講的是你的租戶的狀態，不是目標資源存不存在，所以據此推不出 任何關於那個 person 的事——沒有要遮蔽的東西。

403 的代碼逐字來自授權決定。 它們告訴你要去修哪裡：client_disabled 是被停用 （不是不存在，那是 client_unknown）；actor_unknown 表示 token 沒指出誰在操作， 那是簽發端的問題，請附 x-request-id 回報；forbidden 是兜底——新版授權端送來這一版 Gateway 不認識的代碼時用它，仍然是拒絕，不會變成放行，也不會變成可重試的 503。

狀態碼語意

404 同時是「沒有」與「不是你的」

tenant_mismatch（資源不屬於這張 token 的租戶）與 no_relationship（租戶對這個人 沒有有效關係）打在 person 資源上時回 404，不是 403。

這是刻意的：如果「不存在」回 404 而「存在但不是你的」回 403，那麼 403 與 404 的差別 本身就是一支「這個 person 存不存在」的探測器。所以兩者回同一個答案，message 也不 透露線索。不要用狀態碼去推斷某個 id 是否存在——那正是這條規則要擋的事。

tenant_suspended 不折成 404，打在 person 資源上也照樣回 403。它講的是你的租戶 的狀態，不是目標資源存不存在，據此推不出任何關於那個 person 的事——沒有要遮蔽的東西。

403 與 503 永遠不一樣

這是本 API 最重要的一條區分：

平台不會因為授權服務故障就只驗簽放行。 判不了就不放行。

重試策略

退避建議：起始 1 秒，倍增至上限 60 秒，加上 ±20% 抖動，總重試次數設上限。不要無限重試——故障迴圈會把你自己和平台一起拖垮，而且會在限流層被擋。

限流

限流有兩層：租戶層與 service account／使用者層。兩層都可能觸發，回應不會告訴你是哪一層。

• 看 Retry-After 再重試。
• x-ratelimit-remaining 是資訊性欄位，不是契約的一部分，不要拿它當唯一的流量控制依據。
• 合法的大量同步不會被丟棄，只會被要求放慢。需要更高額度請升級方案——用更多帳號繞過沒有用，租戶層還是會撞。

冪等

網路逾時而不知道寫入是否成功時：重讀（GET）確認目前的 ETag 與內容，再決定要不要重送。不要盲目重送一個寫入。

計量以 x-request-id 為 idempotency key，所以重試不會重複扣量——但這是平台的計量保證，不是你的寫入語意保證。