能活過 code review 的 API bug，多半不是邏輯 bug，而是狀態碼 bug。handler 回了 200，body 卻是 { "error": ... }，於是流動端顯示成功畫面、CDN 把這個失敗緩存十分鐘、重試函數庫一次都沒觸發。狀態行是基礎設施會讀的那一段，body 才是你的應用程式讀的。

這篇按你實際要做的決策順序，講那些真正需要選的狀態碼。任何一個碼都可以在 UrsaKit 的 HTTP 狀態碼對照 查到，並附上它出自哪份 RFC。

01狀態碼是契約，不是標籤

一個狀態碼有三種讀者，其中只有一種是你的應用程式：

• 緩存依 2xx / 4xx / 5xx 與 Cache-Control 之類的標頭，決定要不要存這份回應。
• 代理與閘道把 5xx 當成來源端故障，可能因此觸發斷路器。
• 客戶端函數庫依狀態碼決定要重試、更新權杖，還是直接把錯誤顯示給用戶。

HTTP/1.1 201 Created
Location: /v1/orders/8f14e45
Content-Type: application/json

{ "id": "8f14e45", "status": "pending" }

沒有人是為了好玩才解析狀態行，是因為重試邏輯取決於它。

022xx：客戶端可以假設成功了

最值得分清楚的是 200 與 202。如果客戶端必須輪詢，這個請求就還沒結束，202 能在客戶端開始懷疑「寫入是不是丟了」之前就把話說清楚。

033xx：重導與緩存

API 端點請優先選 307 或 308：它們是唯二保證方法與 body 能活著跳過這一站的狀態碼。301 與 302 在歷史上太常被客戶端改寫成 GET。

044xx：問題出在客戶端的請求

大部分的設計決策都集中在這一區，因為「請求壞掉」是一整個家族，不是單一狀態碼。

其中有三個狀態碼帶強制標頭，漏掉就把一個有用的回應變成令人困惑的回應：401 要 WWW-Authenticate、405 要 Allow、429 應該帶 Retry-After。

401 和 403 不能互換。

401 的意思是「我不知道你是誰」，客戶端應該去驗證身分。403 的意思是「我知道你是誰，但你還是不行」——重新驗證沒有幫助。把兩者當成同一件事的客戶端，最後會卡在登入循環裡。

403 與 404 的選擇是安全決策。如果「資源存在」本身敏感——別人的租戶訂單編號、還沒發布的文件——就回 404，讓回應無法被拿來列舉。如果客戶端可以知道資源存在、只是不能動它，那 403 更誠實。

055xx：伺服器或其依賴出了問題

維護與過載期間，請回 503 並帶上 Retry-After。沒有這個標頭，守規矩的客戶端只能退回指數退避；而用 HTTP 402 讓代理付費 這類做法之所以出現，正是因為明確的機器可讀訊號比猜測可靠得多。

不要把真正的失敗包在 200 裡。

帶錯誤物件的 200 會弄壞緩存、讓監控看不到失敗，並關掉每個 HTTP 客戶端本來就有的重試邏輯。回應裡有錯誤，狀態碼就必須說出來。

06值得修掉的常見錯誤

07用三個問題決定

handler 需要一個狀態碼時，按這個順序問：

1. 伺服器有沒有做到被要求的事？ 有，就是 2xx——看是建立了、排隊了，還是回傳了內容，決定 200、201、202 或 204。
2. 如果不是，是呼叫端的問題嗎？ 請求格式壞掉是 400；憑證缺失或錯誤是 401；已驗證但沒權限是 403；資源不存在是 404；狀態衝突是 409；語法正確但值不合法是 422；請求太多是 429。
3. 如果都不是，是我們的問題嗎？ bug 是 500；上游不可用是 502；過載或維護中是 503 並帶 Retry-After。

接著檢查契約細節：201 要 Location、405 要 Allow、401 要 WWW-Authenticate、429 與 503 要 Retry-After、204 的 body 必須是空的。

上線前用 HTTP 狀態碼對照 確認一次——那裡的說明是寫給「正在做決定的人」看的，不是寫給規格律師看的。如果錯誤回應是 JSON，也順手用 JSON 驗證工具 跑一遍：連解析都失敗的錯誤回應，比沒有錯誤回應更糟。