HTTP 狀態碼完整指南
別再猜 401 跟 403 差在哪：以開發者角度巡覽各狀態家族、貼近實務的範例、反模式，以及對 SEO 真的重要的那些碼。
為什麼重要
後端對錯誤回 200 OK，但 body 是 {"error": "Unauthorized"}。前端的泛用錯誤處理因狀態是 200 而當成成功。登入表單陷入迴圈。這類狀態碼小錯會燒掉真實工時——更糟的是扭曲 SEO 爬取與失效連結報告。知道該在何時回哪個碼，本就是工作的一部分。
三個實際場景
缺 token？401。有 token 但無權限？403。資源根本不存在？404。
可預測的客戶端行為
301 會傳遞 PageRank；302 表示暫時、不傳排名。要刻意選擇。
永久轉址、排名移轉
503 搭配 Retry-After 標頭，告訴爬蟲稍後再來，而不是下架索引。
搜尋引擎知道要重試
五大家族一覽
| Range | Family | Common members |
|---|---|---|
| 1xx | Informational | 100 Continue, 101 Switching Protocols |
| 2xx | Success | 200 OK, 201 Created, 204 No Content |
| 3xx | Redirection | 301, 302, 304 Not Modified, 308 |
| 4xx | Client Error | 400, 401, 403, 404, 422, 429 |
| 5xx | Server Error | 500, 502, 503, 504 |
操作說明——使用狀態參考
開啟 HTTP 狀態參考。
依代碼或說明搜尋
輸入「401」或「unauthorized」或「rate limit」。符合的碼會排到前面。
讀標準含義
每則說明規格怎麼定，而不只是 curl 印出什麼。
看實務用法
註解會點出熱門 API（GitHub、Stripe、AWS）何時略有出入。
留意 SEO 影響
每個碼會標註搜尋引擎處理方式（可索引／否、排名是否移轉）。
複製一句話說明
可貼進 API 文件或程式註解。
情境
POST /admin/users
(No Authorization header)建議回應
401 Unauthorized
WWW-Authenticate: Bearer realm="admin"情境
POST /admin/users
Authorization: Bearer eyJ... (valid token, viewer scope)建議回應
403 Forbidden
{"error": "scope_admin_required"}
實用技巧
- 語意上無效但格式正確的輸入用 422（例如 JSON body 欄位型別錯誤）。400 留給格式錯誤的請求。
- 刪除用 204 No Content 比 200 配空 body 更清楚——表示刻意沒有酬載。
- 429／503 務必帶
Retry-After。 讓聰明的客戶端知道何時再試。 - 避免 200 配
error: ...。 那會讓 HTTP 狀態碼失去意義，也搞亂所有監控工具。
常見陷阱
常見陷阱
對「你不能存取這個」回 404
模糊的 404 會隱藏資源存在與否——有時故意為之（例如私人 repo），但一般需登入的 API 較適合 403，讓客戶端知道是權限問題。
常見陷阱
把 302 快取成永久
依規格 302 是暫時轉址，但部分中介會積極快取。若為永久轉址請用 301（或 308 以保留 HTTP 方法）。
常見陷阱
客戶端錯誤卻回 500
500 代表伺服器錯誤。若客戶端送錯資料，應回 4xx——否則你的告警會為他們程式碼的問題而狂響。
何時不適合用這套
- 設計全新協定——HTTP 狀態碼綁在 HTTP 語意上；gRPC、WebSocket 與自訂協定有自己的慣例。
- 應用程式內錯誤回報——應用層錯誤碼應放在 body，與 HTTP 碼並存。
- 監控——APM 應自動分類狀態碼；本參考用在出貨前的設計決策。
FAQ
301 與 308 差在哪？
兩者都是永久轉址。308保證保留 HTTP 方法；歷史上 301 曾允許客戶端在追蹤時把 POST 改成 GET。
是，RFC 2324（1998 年 4 月 1 日），RFC 7168 再次提及。玩笑回應，正式 API 不會用。
該暴露框架專用碼嗎（例如 419、440）？
能避免就避免。盡量用 IANA 註冊的集合，泛用客戶端才懂。