狀態碼 · HTTP 接口設計指北

## 狀態碼 ### [](https://github.com/bolasblack/http-api-guide#請求成功)請求成功 * 200?**OK**?: 請求執行成功并返回相應數據，如?`GET`?成功 * 201?**Created**?: 對象創建成功并返回相應資源數據，如?`POST`?成功；創建完成后響應頭中應該攜帶頭標?`Location`?，指向新建資源的地址 * 202?**Accepted**?: 接受請求，但無法立即完成創建行為，比如其中涉及到一個需要花費若干小時才能完成的任務。返回的實體中應該包含當前狀態的信息，以及指向處理狀態監視器或狀態預測的指針，以便客戶端能夠獲取最新狀態。 * 204?**No Content**?: 請求執行成功，不返回相應資源數據，如?`PATCH`?，?`DELETE`?成功 ### [](https://github.com/bolasblack/http-api-guide#重定向)重定向 **重定向的新地址都需要在響應頭?`Location`?中返回** * 301?**Moved Permanently**?: 被請求的資源已永久移動到新位置 * 302?**Found**?: 請求的資源現在臨時從不同的 URI 響應請求 * 303?**See Other**?: 對應當前請求的響應可以在另一個 URI 上被找到，客戶端應該使用?`GET`?方法進行請求 * 307?**Temporary Redirect**?: 對應當前請求的響應可以在另一個 URI 上被找到，客戶端應該保持原有的請求方法進行請求 ### [](https://github.com/bolasblack/http-api-guide#條件請求)條件請求 * 304?**Not Modified**?: 資源自從上次請求后沒有再次發生變化，主要使用場景在于實現[數據緩存](https://github.com/bolasblack/http-api-guide#user-content-%E6%95%B0%E6%8D%AE%E7%BC%93%E5%AD%98) * 409?**Conflict**?: 請求操作和資源的當前狀態存在沖突。主要使用場景在于實現[并發控制](https://github.com/bolasblack/http-api-guide#user-content-%E5%B9%B6%E5%8F%91%E6%8E%A7%E5%88%B6) * 412?**Precondition Failed**?: 服務器在驗證在請求的頭字段中給出先決條件時，沒能滿足其中的一個或多個。主要使用場景在于實現[并發控制](https://github.com/bolasblack/http-api-guide#user-content-%E5%B9%B6%E5%8F%91%E6%8E%A7%E5%88%B6) ### [](https://github.com/bolasblack/http-api-guide#客戶端錯誤)客戶端錯誤 * 400?**Bad Request**?: 請求體包含語法錯誤 * 401?**Unauthorized**?: 需要驗證用戶身份，如果服務器就算是身份驗證后也不允許客戶訪問資源，應該響應?`403 Forbidden` * 403?**Forbidden**?: 服務器拒絕執行 * 404?**Not Found**?: 找不到目標資源 * 405?**Method Not Allowed**?: 不允許執行目標方法，響應中應該帶有?`Allow`?頭，內容為對該資源有效的 HTTP 方法 * 406?**Not Acceptable**?: 服務器不支持客戶端請求的內容格式，但響應里會包含服務端能夠給出的格式的數據，并在?`Content-Type`?中聲明格式名稱 * 410?**Gone**?: 被請求的資源已被刪除，只有在確定了這種情況是永久性的時候才可以使用，否則建議使用?`404 Not Found` * 413?**Payload Too Large**?:?`POST`?或者?`PUT`?請求的消息實體過大 * 415?**Unsupported Media Type**?: 服務器不支持請求中提交的數據的格式 * 422?**Unprocessable Entity**?: 請求格式正確，但是由于含有語義錯誤，無法響應 * 428?**Precondition Required**?: 要求先決條件，如果想要請求能成功必須滿足一些預設的條件 ### [](https://github.com/bolasblack/http-api-guide#服務端錯誤)服務端錯誤 * 500?**Internal Server Error**?: 服務器遇到了一個未曾預料的狀況，導致了它無法完成對請求的處理。 * 501?**Not Implemented**?: 服務器不支持當前請求所需要的某個功能。 * 502?**Bad Gateway**?: 作為網關或者代理工作的服務器嘗試執行請求時，從上游服務器接收到無效的響應。 * 503?**Service Unavailable**?: 由于臨時的服務器維護或者過載，服務器當前無法處理請求。這個狀況是臨時的，并且將在一段時間以后恢復。如果能夠預計延遲時間，那么響應中可以包含一個`Retry-After`?頭用以標明這個延遲時間（內容可以為數字，單位為秒；或者是一個?[HTTP 協議指定的時間格式](http://tools.ietf.org/html/rfc2616#section-3.3)）。如果沒有給出這個?`Retry-After`?信息，那么客戶端應當以處理 500 響應的方式處理它。 `501`?與?`405`?的區別是：`405`?是表示服務端不允許客戶端這么做，`501`?是表示客戶端或許可以這么做，但服務端還沒有實現這個功能相關資料： * [RFC 里的狀態碼列表](http://tools.ietf.org/html/rfc7231#page-49) * [RFC 4918](http://tools.ietf.org/html/rfc4918)?- 422 狀態碼的定義 * [RFC 6585](http://tools.ietf.org/html/rfc6585)?- 新增的四個 HTTP 狀態碼，[中文版](http://www.oschina.net/news/28660/new-http-status-codes) * [維基百科上的《 HTTP 狀態碼》詞條](http://zh.wikipedia.org/wiki/HTTP%E7%8A%B6%E6%80%81%E7%A0%81) * [Do I need to use http redirect code 302 or 307? - Stack Overflow](http://stackoverflow.com/questions/2467664/do-i-need-to-use-http-redirect-code-302-or-307) * [400 vs 422 response to POST of data](http://stackoverflow.com/questions/16133923/400-vs-422-response-to-post-of-data)