前言
在 Web 開發與 API 串接過程中，HTTP 狀態碼是伺服器與客戶端溝通的核心語言。熟悉各類狀態碼的含義，不僅能加速除錯，更能協助設計更健壯的錯誤處理機制。本文系統整理官方 RFC 規範與實務常見代碼，提供一份可直接套用的速查參考。
狀態碼分類總覽
| 類別 | 語意 | 典型場景 |
|---|
| 1xx | 資訊回應 | 請求已收到，繼續處理 |
| 2xx | 成功回應 | 請求正常完成 |
| 3xx | 重導向 | 需進一步動作才能完成請求 |
| 4xx | 客戶端錯誤 | 請求語法錯誤或無法滿足 |
| 5xx | 伺服器錯誤 | 伺服器處理合法請求時失敗 |
常用狀態碼詳細說明
1xx 資訊類
- 100 Continue：客戶端應繼續發送請求主體，常用於大檔案上傳前的預檢。
- 101 Switching Protocols：伺服器同意切換協議（如 HTTP 升級為 WebSocket）。
2xx 成功類
- 200 OK：標準成功回應，GET 返回資源、POST 返回處理結果。
- 201 Created：資源建立成功，回應 Header 中的 Location 指向新資源 URL。
- 202 Accepted：請求已接受但尚未處理完成，常用於非同步任務。
- 204 No Content：請求成功但無回應主體，適合 DELETE 或僅需確認的操作。
- 206 Partial Content：範圍請求成功，支援斷點續傳與多執行緒下載。
3xx 重導向類
- 301 Moved Permanently：資源永久移動，搜尋引擎會轉移權重，瀏覽器會快取。
- 302 Found：臨時重導向，原 URL 保留，搜尋引擎不轉移權重。
- 304 Not Modified：協商快取命中，配合 ETag/Last-Modified 使用，節省頻寬。
- 307 Temporary Redirect：臨時重導向且保持原請求方法（POST 不會變成 GET）。
4xx 客戶端錯誤
- 400 Bad Request：請求語法錯誤、參數格式不符、JSON 解析失敗等。
- 401 Unauthorized：未提供或提供無效認證憑證（Token 過期、簽名錯誤）。
- 403 Forbidden：已認證但權限不足，RBAC/ABAC 拒絕存取。
- 404 Not Found：資源不存在，路徑錯誤或資源已刪除。
- 405 Method Not Allowed：HTTP 方法不被允許，需在 Allow 標頭列出支援方法。
- 409 Conflict：資源衝突，如樂觀鎖版本號不匹配、唯一鍵重複。
- 413 Payload Too Large：請求主體超過伺服器限制（Nginx client_max_body_size）。
- 422 Unprocessable Entity：語法正確但語意錯誤（驗證失敗），WebDAV/RFC 4918 擴展。
- 429 Too Many Requests：觸發速率限制，配合 Retry-After 標頭引導客戶端重試。
5xx 伺服器錯誤
- 500 Internal Server Error：未捕獲的例外、程式邏輯錯誤、資源耗盡。
- 502 Bad Gateway：反向代理（Nginx/Cloudflare）無法從上游取得有效回應。
- 503 Service Unavailable：服務暫時不可用（維護窗、過載、熔斷器開啟），建議回傳 Retry-After。
- 504 Gateway Timeout：代理等待上游回應逾時，常見於長時間運算或資料庫鎖死。
實務最佳實踐建議
- 語意化回應：不要濫用 200 包裝錯誤，正確使用 4xx/5xx 讓客戶端能程式化處理。
- 錯誤細節：回應主體採用 RFC 7807 Problem Details 格式（type, title, status, detail, instance）。
- 快取策略：善用 304、ETag、Cache-Control 減少頻寬與延遲。
- 監控告警：對 5xx、429、409 設定即時告警，縮短 MTTR。
結語
HTTP 狀態碼是分散式系統的通用契約。深入理解並規範使用，能讓 API 更具可觀測性、可維護性與開發者友善度。建議將本表收藏，並在 Code Review 時作為檢核依據。
