HTTP 狀態碼:它們的意義以及何時使用它們

你的 API 回傳 200。回應主體說 {"error": "Not found"}。

這是錯的。狀態碼的存在是有原因的。正確使用它們。

五個類別

1xx — 資訊性。實務上很少見。

2xx — 成功。請求有效。

3xx — 重新導向。到別的地方去。

4xx — 客戶端錯誤。你做錯了什麼。

5xx — 伺服器錯誤。我們做錯了什麼。

你實際會使用的代碼

成功 (2xx)

200 OK — 標準成功。用於回傳資料的 GET 請求。

201 Created — 資源已創建。用於創建東西的成功 POST 之後。

204 No Content — 成功,但沒有東西要回傳。用於不回傳資料的 DELETE 或更新。

客戶端錯誤 (4xx)

400 Bad Request — 格式錯誤的請求。無效的 JSON、缺少必填欄位、錯誤的資料類型。

401 Unauthorized — 沒有驗證。使用者需要登入。

403 Forbidden — 已驗證但不允許。使用者存在但缺乏權限。

404 Not Found — 資源不存在。經典。

409 Conflict — 請求與當前狀態衝突。重複的使用者名稱、版本不匹配。

422 Unprocessable Entity — 語法正確但語義錯誤。有效的 JSON 但違反業務規則。

429 Too Many Requests — 速率限制。慢下來。

伺服器錯誤 (5xx)

500 Internal Server Error — 通用伺服器故障。某些東西崩潰了。

502 Bad Gateway — 上游伺服器失敗。你的伺服器正常,但它依賴的東西不正常。

503 Service Unavailable — 暫時關閉。維護或過載。

504 Gateway Timeout — 上游伺服器沒有及時回應。

常見錯誤

主體中有錯誤的 200。 如果是錯誤,使用錯誤狀態碼。不要讓客戶端解析主體來知道是否成功。

驗證錯誤用 500。 使用者提交了錯誤資料?那是 400 或 422,不是 500。伺服器沒壞——請求壞了。

401 vs 403 混淆。 401 表示「你是誰?」403 表示「我知道你是誰,但不行。」

所有東西都用 404。「找不到」並不總是正確的答案。錯誤的方法?405。速率限制?429。

設計 API

要具體。客戶端可以智慧地處理特定錯誤。通用錯誤意味著通用處理。

在主體中包含錯誤詳情:

{
  "error": "validation_failed",
  "message": "Email format is invalid",
  "field": "email"
}

狀態碼說明問題的類別。主體具體解釋。

作為客戶端處理狀態碼

2xx — 解析回應,正常進行。

4xx — 你的錯。記錄,向使用者顯示,修正請求。

5xx — 伺服器的錯。可能以退避重試。可能警報。

3xx — 自動跟隨重新導向(大多數 HTTP 客戶端都這樣做)。

不要只檢查 200。檢查成功 (2xx) 並適當地處理其他情況。

---

狀態碼是溝通。正確使用它們,API 變得自我記錄。誤用它們,除錯變成猜測遊戲。