萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網頁製作 >> HTML5 教學

HTTP 狀態碼權威中文參考:五大類別 60+ 代碼含義、觸發場景與除錯策略

HTTP 狀態碼是伺服器對請求的標準化回應碼,分五大類別。精通代碼含義與觸發情境,能讓 API 設計更符合 REST 語意、前端錯誤處理更精準、運維排查更高效。本文提供最完整中文對照表與實戰除錯指南。

1xx 資訊回應 — 協議層面交換

代碼名稱觸發場景客戶端行為
100Continue請求含 `Expect: 100-continue`,伺服器準備好接收主體繼續發送請求主體
101Switching ProtocolsWebSocket 升級 (`Upgrade: websocket`)、HTTP/2 升級切換協議處理
102Processing (WebDAV)請求處理需時較長,避免客戶端超時等待最終回應
103Early Hints預載關鍵資源 (Link: rel=preload),配合 2xx 回應開始預載資源

2xx 成功 — 請求正確處理

代碼名稱語意細節典型用例
200OKGET/POST/PUT 成功,實體在回應主體網頁、API 成功回應
201Created資源建立成功,`Location` 指向新資源POST /api/users 回傳 201 + Location
202Accepted非同步受理,處理中,可提供狀態查詢端點長時間任務 (影片轉碼、報表生成)
203Non-Authoritative Information代理/快取回應,非源站原始CDN 邊緣節點回應
204No Content成功但無實體,瀏覽器保持當前頁DELETE 成功、儲存設定無需回傳資料
205Reset Content成功並要求重置表單/視圖提交後清空表單
206Partial Content範圍請求 (`Range` 標頭),支援斷點續傳、多執行緒下載影片拖曳播放、大檔下載
207Multi-Status (WebDAV)多資源狀態,XML 格式批次操作回應
208Already Reported (WebDAV)避免重複列舉綁定—
226IM Used例項操控回應Delta encoding

3xx 重導向 — 需進一步動作

代碼名稱關鍵差異SEO 影響
300Multiple Choices提供選項清單 (Link 標頭或實體)罕用
301Moved Permanently**永久移動**,請求方法可變 GET,搜尋引擎**轉移權重**域名遷移、HTTPS 強制、永久重組
302Found**暫時移動**,方法可變 GET,**保留原 URL 權重**活動頁、A/B 測試、裝置適配
303See Other**必須用 GET** 重新請求 `Location`POST 表單提交後導向結果頁 (PRG 模式)
304Not Modified快取有效 (`If-None-Match`/`If-Modified-Since`),**無實體**節省頻寬、CDN 快取命中
305Use Proxy**必須透過 `Location` 指定代理** (安全風險,極少用)—
307Temporary Redirect暫時移動,**保持原方法** (POST 維持 POST)API 版本暫時遷移、維護窗口
308Permanent Redirect永久移動,**保持原方法** (RFC 7538)API 端點永久遷移、保持 POST/PUT

4xx 客戶端錯誤 — 請求本身有問題

代碼名稱常見原因前端處理建議
400Bad RequestJSON 格式錯、缺必填欄位、驗證失敗顯示欄位級錯誤、引導修正
401Unauthorized未登入、Token 過期/無效、`WWW-Authenticate` 指引導向登入頁、自動刷新 Token
403Forbidden已認證但無權限 (RBAC/ABAC 拒絕)顯示「權限不足」、提供申請入口
404Not Found資源不存在、路由未匹配友善 404 頁 + 搜尋/網站地圖
405Method Not Allowed路由存在但不支援該 Method,回應 `Allow` 標頭檢查 API 文檔、修正呼叫方式
406Not Acceptable無法滿足 `Accept` 標頭 (格式/語言/編碼)調整請求標頭、支援預設格式
408Request Timeout客戶端傳輸過慢超過伺服器閾值重試、檢查網路、分塊上傳
409Conflict資源衝突 (唯一鍵重複、樂觀鎖版本衝突)提示衝突細節、提供合併/覆蓋選項
410Gone資源永久移除、不再提供 (比 404 更明確)下架商品、舊版 API 移除
411Length Required缺 `Content-Length` (拒絕 chunked 或流式)補上標頭或改用支援 chunked 端點
413Payload Too Large請求體超過限制 (Nginx `client_max_body_size`)壓縮/分塊/預簽名直傳物件儲存
414URI Too LongGET 參數過長、轉 POST改 POST + Body、縮短參數
415Unsupported Media Type`Content-Type` 不支援 (如傳 `image/tiff` 只收 `jpeg/png`)修正 Content-Type、轉碼
422Unprocessable Entity (WebDAV)語法正確但語義錯誤 (業務規則違反)回傳詳細欄位錯誤結構
429Too Many Requests速率限制,回應 `Retry-After`指數退避重試、顯示倒數計時
431Request Header Fields Too LargeCookie/標頭過大清理 Cookie、拆分子域
451Unavailable For Legal Reasons法律審查/法院命令移除顯示法律說明、聯繫法務

5xx 伺服器錯誤 — 伺服器端失敗

代碼名稱典型原因運維應對
500Internal Server Error未捕獲例外、配置錯誤、資源耗盡檢查應用日誌、APM 追蹤、錯誤追蹤 (Sentry)
501Not Implemented不支援的 Method/功能確認路由實作、版本相容
502Bad Gateway反向代理/閘道收到上游無效回應 (Nginx→App 崩潰/超時)檢查上游健康、超時設定、熔斷器
503Service Unavailable維護中、過載、熔斷開啟、Pod 未就緒回應 `Retry-After`、健康檢查端點、擴容
504Gateway Timeout代理等待上游超時 (Nginx `proxy_read_timeout`)優化上游效能、調大超時、非同步化
505HTTP Version Not Supported不支援請求 HTTP 版本 (如 HTTP/0.9、HTTP/3 未啟用)升級伺服器、協商降級
507Insufficient Storage (WebDAV)儲存空間不足擴容、清理、配額管理
511Network Authentication Required網關要求認證 (Captive Portal)導向認證頁面

實戰除錯三板斧

  1. Network 面板:看實際狀態碼、Request/Response Headers、Timing (TTFB、Content Download)
  2. 結構化日誌 + 追蹤 ID:請求進入生成 `X-Request-ID`,串聯 Gateway → App → DB 全鏈路
  3. 錯誤碼語意化回傳:API 回傳 `{ "error": { "code": "VALIDATION_FAILED", "message": "...", "details": [...] } }` 而非純 HTTP 碼

API 設計黃金法則

  • **2xx = 成功** (含 202 非同步受理)
  • **4xx = 客戶端可修正** (提供足夠資訊讓前端引導用戶)
  • **5xx = 伺服器端須介入** (記錄告警、自動化修復、On-call 機制)
  • **3xx 謹慎用**:301/308 永久、302/307 暫時、303 PRG、304 快取,**避免重導向鏈 > 2 跳**

將此表內化為肌肉記憶,API 設計、前端錯誤處理、運維值班將事半功倍。

copyright © 萬盛學電腦網 all rights reserved