[ADP-200] HTTP 狀態碼
reviewing phase 1
- 重新審視是否文件化標準
- 加入關聯ADP連結
HTTP 狀態碼是標準化的代碼，用於表示 HTTP 請求的結果。這些代碼分為五類:
- 1xx (資訊性): 請求已收到，處理過程正在繼續。
- 2xx (成功): 請求已成功接收、理解並接受。
- 3xx (重定向): 需要採取進一步行動才能完成請求。
- 4xx (客戶端錯誤): 請求包含錯誤的語法或無法實現。
- 5xx (伺服器錯誤): 伺服器無法實現有效請求。
HTTP 狀態碼使用情況
| 代碼 | 描述 | 使用 | 文件 |
|---|---|---|---|
| 成功代碼 | |||
| 200 | OK | 使用 | 記錄所有 |
| 201 | Created | 使用 | 記錄 POST, PUT |
| 202 | Accepted | 使用 | 記錄 POST, PUT, PATCH, DELETE |
| 204 | No Content | 使用 | 記錄 POST, PUT, PATCH, DELETE |
| 205 | Reset Content | 不使用 | 所有 |
| 206 | Partial Content | 不用於分頁 | 所有 |
| 207 | Multi-Status | 使用 | 記錄 POST (DELETE) |
| 重定向代碼 | |||
| 301 | Moved Permanently | 不使用 | 所有 |
| 302 | Found | 不使用 | 所有 |
| 303 | See Other | 不使用 | POST, PUT, PATCH, DELETE |
| 304 | Not Modified | 記錄 | GET, HEAD |
| 307 | Temporary Redirect | 不使用 | 所有 |
| 308 | Permanent Redirect | 不使用 | 所有 |
| 客戶端錯誤代碼 | |||
| 400 | Bad Request | 使用 | 記錄所有 |
| 401 | Unauthorized | 使用 | 不記錄所有 |
| 403 | Forbidden | 不記錄 | 所有 |
| 404 | Not Found | 使用 | 不記錄所有 |
| 405 | Method Not Allowed | 記錄 | 所有 |
| 406 | Not Acceptable | 使用 | 不記錄所有 |
| 407 | Proxy Authentication Required | 不使用 | 所有 |
| 408 | Request Timeout | 不使用 | 所有 |
| 409 | Conflict | 記錄 | POST, PUT, PATCH, DELETE |
| 410 | Gone | 不記錄 | 所有 |
| 411 | Length Required | 記錄 | POST, PUT, PATCH |
| 412 | Precondition Failed | 使用 | 不記錄 PUT, PATCH, DELETE |
| 413 | Payload Too Large | 使用 | 所有 |
| 415 | Unsupported Media Type | 使用 | 不記錄 POST, PUT, PATCH |
| 417 | Expectation Failed | 不使用 | 所有 |
| 418 | I'm a Teapot | 不使用 | 所有 |
| 422 | Unprocessable Content | 不使用 | 所有 |
| 423 | Locked | 記錄 | PUT, PATCH, DELETE |
| 424 | Failed Dependency | 不使用 | 所有 |
| 428 | Precondition Required | 使用 | 不記錄所有 |
| 429 | Too Many Requests | 使用 | 不記錄所有 |
| 431 | Request Header Fields Too Large | 不記錄 | 所有 |
| 伺服器端錯誤代碼 | |||
| 500 | Internal Server Error | 使用 | 不記錄所有 |
| 501 | Not Implemented | 記錄 | 所有 |
| 502 | Bad Gateway | 無意義 | |
| 503 | Service Unavailable | 使用 | 不記錄所有 |
| 504 | Gateway Timeout | 使用 | 所有 |
| 505 | HTTP Version Not Supported | 不使用 | 所有 |
| 507 | Insufficient Storage | 不記錄 | POST, PUT, PATCH |
| 511 | Network Authentication Required | 不使用 | 所有 |
圖例:
- 使用: 常見且易於理解的狀態碼，應在適當情況下使用。這並不意味著每個操作都必須返回此代碼。
- 不使用: 該狀態碼被認為不適合從 RESTful API 返回。它可能適用於其他情況，例如由反向代理返回或用於網頁。
- 記錄: 如果 API 可能返回該狀態碼，應在 API 規範中記錄。
- 不記錄: 該狀態碼具有公認的標準含義，因此只有在有特定於操作的細節需要添加時才應記錄。
HTTP 狀態碼 - 使用指南
| 代碼 | 描述 | 何時使用 | 不使用的原因(如適用) |
|---|---|---|---|
| 成功代碼 | |||
| 200 | OK | 標準成功回應。當請求成功且有回應主體時使用。 | |
| 201 | Created | 當成功創建資源時使用。返回創建的資源或設置帶有新資源 URI 的 Location 標頭。 | |
| 202 | Accepted | 當請求已被接受處理，但處理尚未完成時使用。適用於異步操作。 | |
| 204 | No Content | 當請求成功但沒有回應主體時使用(例如，成功的 DELETE 或 PUT 請求)。 | |
| 205 | Reset Content | 用於交互式用例，如清除表單。在 REST API 中沒有理由使用。 | |
| 206 | Partial Content | 用於回應範圍請求，僅返回由字節範圍指示的資源的一部分。不用於分頁，分頁應使用正常的 200。在罕見情況下可能有用，但大多數 API 不需要。 | |
| 207 | Multi-Status | 用於批量或批處理請求，其中回應包含多個部分的狀態。通常與 POST 或 DELETE 一起使用。 | |
| 重定向代碼 | |||
| 301 | Moved Permanently | 此請求和所有未來請求應定向到給定的 URI。不建議用於 API，因為通常不使用重定向代碼。 | |
| 302 | Found | 臨時重定向;某些客戶端可能會將方法從 POST 更改為 GET。主要用於在瀏覽器中取消和重定向表單提交。不建議用於 API。 | |
| 303 | See Other | 表示可以使用 GET 方法在另一個 URI 下找到回應。不建議用於 API。原始設計用於 API 中的長時間運行任務。但我們已經使用 202 + Location 替代它，請參見 ../HTTP%20Semantics%209242628693f84e209daf705d397c27db/%5BADP-357%5D%20Long%20running%20job%20e6872e32e7824847b778f11b7fd373db.md。 | |
| 304 | Not Modified | 用於條件 GET 或 HEAD 請求，其中自提供的日期或版本以來資源未被修改。 | |
| 307 | Temporary Redirect | 表示資源暫時位於另一個 URI，保持相同的方法。不建議用於 API。 | |
| 308 | Permanent Redirect | 表示資源永久位於另一個 URI，保持相同的方法。不建議用於 API。 | |
| 客戶端錯誤代碼 | |||
| 400 | Bad Request | 用於語法不正確或格式錯誤的請求。 | |
| 401 | Unauthorized | 當需要身份驗證且身份驗證失敗或尚未提供時使用。通常意味著"未經身份驗證"。 | 應引用通用組件.responses.UnauthorizedError |
| 403 | Forbidden | 當客戶端沒有訪問資源的權限時使用。 | 只記錄特定情況。 |
| 404 | Not Found | 當找不到請求的資源時使用。 | 應引用通用組件.responses.NotFoundError |
| 405 | Method Not Allowed | 當使用的 HTTP 方法不允許用於該資源時使用。 | |
| 406 | Not Acceptable | 當請求的資源只能生成不符合請求中發送的 Accept 標頭的內容時使用。 | |
| 407 | Proxy Authentication Failed | 在 API 中很少使用 | |
| 408 | Request Timeout | 伺服器等待請求時超時。不應用於 API。 | |
| 409 | Conflict | 當由於與資源當前狀態衝突而無法處理請求時使用。 | |
| 410 | Gone | 當請求的資源不再可用且將來也不會可用時使用。 | |
| 411 | Length Required | 當伺服器要求請求中包含 Content-Length 標頭時使用。 | |
| 412 | Precondition Failed | 用於條件請求，其中不滿足前提條件。通常與 If-Match 一起用於樂觀鎖定。 | |
| 413 | Payload Too Large | 請求標頭或主體超過定義的限制。這可能發生在包含許多範圍的大型 JWT 或大型 HTTP 主體中。 | |
| 415 | Unsupported Media Type | 當伺服器不支持請求數據的媒體格式時使用。 | |
| 417 | Expectation Failed | 客戶端使用了伺服器不支持的 Expect 標頭。 | |
| 418 | I'm a Teapot | 在 RFC 2324 中定義為玩笑。 | |
| 422 | Unprocessable Entity | 伺服器理解內容類型但無法處理內容。400 涵蓋了大多數用例，沒有明確的區分優勢。 | |
| 423 | Locked | 當資源被鎖定且無法訪問時使用。通常用於悲觀鎖定。 | |
| 424 | Failed Dependency | 由於先前請求失敗而導致請求失敗。不適用於 RESTful API。通常用於 WebDAV。 | |
| 428 | Precondition Required | 當伺服器要求請求為條件請求時使用，以防止"丟失更新"問題。 | |
| 429 | Too Many Requests | 當客戶端在給定時間內發送了太多請求時使用("速率限制")。 | |
| 431 | Request Header Fields Too Large | 伺服器無法處理請求，因為請求標頭太大。 | |
| 伺服器端錯誤代碼 | |||
| 500 | Internal Server Error | 用於伺服器遇到意外情況時的通用伺服器錯誤。 | |
| 501 | Not Implemented | 當伺服器不支持實現請求所需的功能時使用。 | |
| 502 | Bad Gateway | 伺服器從入站伺服器收到無效回應。 | |
| 503 | Service Unavailable | 當伺服器未準備好處理請求時使用，通常是由於維護或過載。客戶端重試可能是合理的。 | |
| 504 | Gateway Timeout | 當伺服器作為網關或代理時，未能及時從上游伺服器接收回應時使用。 | |
| 505 | HTTP Version Not Supported | 伺服器不支持請求中使用的 HTTP 協議版本。 | |
| 507 | Insufficient Storage | 伺服器無法按需要存儲資源以完成請求。為 WebDAV 設計，見 https://datatracker.ietf.org/doc/html/rfc4918#section-11.5 | |
| 511 | Network Authentication Required | 客戶端需要進行身份驗證以獲得網絡訪問權限。 |
INFO
💡 關於 4xx 和 5xx 回應詳情，請參見錯誤設計。