HTTP 狀態碼是伺服器對請求的標準化回應碼,分五大類別。精通代碼含義與觸發情境,能讓 API 設計更符合 REST 語意、前端錯誤處理更精準、運維排查更高效。本文提供最完整中文對照表與實戰除錯指南。
| 代碼 | 名稱 | 觸發場景 | 客戶端行為 |
|---|---|---|---|
| 100 | Continue | 請求含 `Expect: 100-continue`,伺服器準備好接收主體 | 繼續發送請求主體 |
| 101 | Switching Protocols | WebSocket 升級 (`Upgrade: websocket`)、HTTP/2 升級 | 切換協議處理 |
| 102 | Processing (WebDAV) | 請求處理需時較長,避免客戶端超時 | 等待最終回應 |
| 103 | Early Hints | 預載關鍵資源 (Link: rel=preload),配合 2xx 回應 | 開始預載資源 |
| 代碼 | 名稱 | 語意細節 | 典型用例 |
|---|---|---|---|
| 200 | OK | GET/POST/PUT 成功,實體在回應主體 | 網頁、API 成功回應 |
| 201 | Created | 資源建立成功,`Location` 指向新資源 | POST /api/users 回傳 201 + Location |
| 202 | Accepted | 非同步受理,處理中,可提供狀態查詢端點 | 長時間任務 (影片轉碼、報表生成) |
| 203 | Non-Authoritative Information | 代理/快取回應,非源站原始 | CDN 邊緣節點回應 |
| 204 | No Content | 成功但無實體,瀏覽器保持當前頁 | DELETE 成功、儲存設定無需回傳資料 |
| 205 | Reset Content | 成功並要求重置表單/視圖 | 提交後清空表單 |
| 206 | Partial Content | 範圍請求 (`Range` 標頭),支援斷點續傳、多執行緒下載 | 影片拖曳播放、大檔下載 |
| 207 | Multi-Status (WebDAV) | 多資源狀態,XML 格式 | 批次操作回應 |
| 208 | Already Reported (WebDAV) | 避免重複列舉綁定 | — |
| 226 | IM Used | 例項操控回應 | Delta encoding |
| 代碼 | 名稱 | 關鍵差異 | SEO 影響 |
|---|---|---|---|
| 300 | Multiple Choices | 提供選項清單 (Link 標頭或實體) | 罕用 |
| 301 | Moved Permanently | **永久移動**,請求方法可變 GET,搜尋引擎**轉移權重** | 域名遷移、HTTPS 強制、永久重組 |
| 302 | Found | **暫時移動**,方法可變 GET,**保留原 URL 權重** | 活動頁、A/B 測試、裝置適配 |
| 303 | See Other | **必須用 GET** 重新請求 `Location` | POST 表單提交後導向結果頁 (PRG 模式) |
| 304 | Not Modified | 快取有效 (`If-None-Match`/`If-Modified-Since`),**無實體** | 節省頻寬、CDN 快取命中 |
| 305 | Use Proxy | **必須透過 `Location` 指定代理** (安全風險,極少用) | — |
| 307 | Temporary Redirect | 暫時移動,**保持原方法** (POST 維持 POST) | API 版本暫時遷移、維護窗口 |
| 308 | Permanent Redirect | 永久移動,**保持原方法** (RFC 7538) | API 端點永久遷移、保持 POST/PUT |
| 代碼 | 名稱 | 常見原因 | 前端處理建議 |
|---|---|---|---|
| 400 | Bad Request | JSON 格式錯、缺必填欄位、驗證失敗 | 顯示欄位級錯誤、引導修正 |
| 401 | Unauthorized | 未登入、Token 過期/無效、`WWW-Authenticate` 指引 | 導向登入頁、自動刷新 Token |
| 403 | Forbidden | 已認證但無權限 (RBAC/ABAC 拒絕) | 顯示「權限不足」、提供申請入口 |
| 404 | Not Found | 資源不存在、路由未匹配 | 友善 404 頁 + 搜尋/網站地圖 |
| 405 | Method Not Allowed | 路由存在但不支援該 Method,回應 `Allow` 標頭 | 檢查 API 文檔、修正呼叫方式 |
| 406 | Not Acceptable | 無法滿足 `Accept` 標頭 (格式/語言/編碼) | 調整請求標頭、支援預設格式 |
| 408 | Request Timeout | 客戶端傳輸過慢超過伺服器閾值 | 重試、檢查網路、分塊上傳 |
| 409 | Conflict | 資源衝突 (唯一鍵重複、樂觀鎖版本衝突) | 提示衝突細節、提供合併/覆蓋選項 |
| 410 | Gone | 資源永久移除、不再提供 (比 404 更明確) | 下架商品、舊版 API 移除 |
| 411 | Length Required | 缺 `Content-Length` (拒絕 chunked 或流式) | 補上標頭或改用支援 chunked 端點 |
| 413 | Payload Too Large | 請求體超過限制 (Nginx `client_max_body_size`) | 壓縮/分塊/預簽名直傳物件儲存 |
| 414 | URI Too Long | GET 參數過長、轉 POST | 改 POST + Body、縮短參數 |
| 415 | Unsupported Media Type | `Content-Type` 不支援 (如傳 `image/tiff` 只收 `jpeg/png`) | 修正 Content-Type、轉碼 |
| 422 | Unprocessable Entity (WebDAV) | 語法正確但語義錯誤 (業務規則違反) | 回傳詳細欄位錯誤結構 |
| 429 | Too Many Requests | 速率限制,回應 `Retry-After` | 指數退避重試、顯示倒數計時 |
| 431 | Request Header Fields Too Large | Cookie/標頭過大 | 清理 Cookie、拆分子域 |
| 451 | Unavailable For Legal Reasons | 法律審查/法院命令移除 | 顯示法律說明、聯繫法務 |
| 代碼 | 名稱 | 典型原因 | 運維應對 |
|---|---|---|---|
| 500 | Internal Server Error | 未捕獲例外、配置錯誤、資源耗盡 | 檢查應用日誌、APM 追蹤、錯誤追蹤 (Sentry) |
| 501 | Not Implemented | 不支援的 Method/功能 | 確認路由實作、版本相容 |
| 502 | Bad Gateway | 反向代理/閘道收到上游無效回應 (Nginx→App 崩潰/超時) | 檢查上游健康、超時設定、熔斷器 |
| 503 | Service Unavailable | 維護中、過載、熔斷開啟、Pod 未就緒 | 回應 `Retry-After`、健康檢查端點、擴容 |
| 504 | Gateway Timeout | 代理等待上游超時 (Nginx `proxy_read_timeout`) | 優化上游效能、調大超時、非同步化 |
| 505 | HTTP Version Not Supported | 不支援請求 HTTP 版本 (如 HTTP/0.9、HTTP/3 未啟用) | 升級伺服器、協商降級 |
| 507 | Insufficient Storage (WebDAV) | 儲存空間不足 | 擴容、清理、配額管理 |
| 511 | Network Authentication Required | 網關要求認證 (Captive Portal) | 導向認證頁面 |
將此表內化為肌肉記憶,API 設計、前端錯誤處理、運維值班將事半功倍。