HTTP 狀態碼詳解與除錯指引

HTTP 狀態碼是伺服器對請求結果的標準化回應。理解常見代碼的意義，可以更快判斷問題出在客戶端、伺服器還是中間環節，並採取正確的除錯步驟。

狀態碼分類

常見代碼說明

• 200 OK：請求成功，回應包含所求資料。
• 201 Created：資源已成功建立。
• 204 No Content：成功但無回應本體。
• 301 / 302：永久或暫時重新導向。瀏覽器或客戶端應跟隨 Location 標頭。
• 304 Not Modified：快取仍有效，無需重新傳輸本體。
• 400 Bad Request：請求語法錯誤或參數無效。
• 401 Unauthorized：需要身份驗證。
• 403 Forbidden：已驗證但無權限存取。
• 404 Not Found：資源不存在。
• 429 Too Many Requests：請求過於頻繁，觸發速率限制。
• 500 Internal Server Error：伺服器內部錯誤。
• 502 / 503 / 504：閘道錯誤、服務不可用或閘道逾時，常見於反向代理或上游服務問題。

除錯方向

4xx 錯誤：先檢查請求 URL、方法、標頭與本體是否符合 API 文件。確認身份驗證權杖是否有效、是否過期。404 時核對路徑與資源 ID。429 時降低請求頻率或實作退避重試。

5xx 錯誤：問題多在伺服器端。可稍後重試，並檢查服務狀態頁。若是自己維護的服務，查看伺服器日誌、上游依賴與資源使用情況。502/504 常與逾時或程序崩潰有關。

瀏覽器開發者工具的 Network 面板可以顯示完整狀態碼、回應標頭與本體，是除錯的第一站。命令列工具如 curl 也方便重現請求。

與快取、CDN 的關係

狀態碼與快取標頭（Cache-Control、ETag 等）共同決定內容如何被儲存與重用。301 會被瀏覽器長期記住，錯誤的永久重新導向可能造成困擾。除錯時可嘗試無痕模式或清除快取，以排除舊回應的干擾。

實務建議

設計 API 時應使用語意正確的狀態碼，並在回應本體提供足夠的錯誤說明（同時避免洩露敏感資訊）。客戶端應根據狀態碼做適當處理，而不是只看是否「成功」。記錄請求 ID 有助於與伺服器日誌關聯。

理解狀態碼是網頁與 API 開發的基本功。Wusper 的工具與服務在發生錯誤時也會回傳相應的 HTTP 狀態，方便診斷。