1. 程式人生 > >API的HTTP Status Code

API的HTTP Status Code

時鐘 超時 重復 策略 替換 authent 例如 現在 實體

響應中的狀態碼

狀態碼

定義

說明

1xx

信息

接收到請求,繼續處理

2xx

成功

操作成功地收到請求,理解和接受

3xx

重定向

為了完成請求,必須采取進一步擦措施

4xx

客戶端錯誤

請求的語法錯誤或不能完全被滿足

5xx

服務端錯誤

服務器無法完成明顯有效的請求

常用的狀態碼:
200 -- 服務器成功返回網頁
301/2 -- 永久/臨時重定向

<?php

header(‘Location: http://www.sf.gg‘); // 默認是 302 重定向

header(‘Location: http://www.sf.gg‘, true, 301); // 301 重定向 // 永久重定向 , true參數指的是用301頭信息替換原來的頭信息?>

307 重定向中保持原有的請求數據.(POST重定向之後,數據丟失)

失敗的狀態碼:
404 -- 請求的網頁不存在
503 -- 服務器暫時不可用
500 -- 服務器內部錯誤

API設計也要尊許HTTP協議,這樣做的好處在於,在接受到API的Response時,客戶端只需要判斷http Code而無需解析請求內容,即可知道如何進行下一步操作。

消息(1開頭) 處理中

此類狀態碼,表示請求已被接受,但仍需要繼續處理。這類響應是臨時響應,只包含狀態行和某些可選的響應頭信息,並以空行結束。由於 HTTP/1.0 協議中沒有定義任何 1xx 狀態碼,所以除非在某些試驗條件下,服務器禁止向此類客戶端發送 1xx 響應。

100 Continue

客戶端應當繼續發送請求。這個臨時響應是用來通知客戶端它的部分請求已經被服務器接收,且仍未被拒絕。客戶端應當繼續發送請求的剩余部分,或者如果請求已經完成,忽略這個響應。服務器必須在請求完成後向客戶端發送一個最終響應。

101 Switching Protocols

服務器已經理解了客戶端的請求,並將通過Upgrade 消息頭通知客戶端采用不同的協議來完成這個請求。在發送完這個響應最後的空行後,服務器將會切換到在Upgrade 消息頭中定義的那些協議。

只有在切換新的協議更有好處的時候才應該采取類似措施。例如,切換到新的HTTP 版本比舊版本更有優勢,或者切換到一個實時且同步的協議以傳送利用此類特性的資源。

102 Processing

WebDAV(RFC 2518)擴展的狀態碼,代表處理將被繼續執行。

成功(2字頭)編輯

這一類型的狀態碼,代表請求已成功被服務器接收、理解、並接受[1] 。

200 OK 成功

請求已成功,請求所希望的響應頭或數據體將隨此響應返回。

201 Created

請求已經被實現,而且有一個新的資源已經依據請求的需要而建立,且其 URI 已經隨Location 頭信息返回。假如需要的資源無法及時建立的話,應當返回 ‘202 Accepted‘。

202 Accepted

服務器已接受請求,但尚未處理。正如它可能被拒絕一樣,最終該請求可能會也可能不會被執行。在異步操作的場合下,沒有比發送這個狀態碼更方便的做法了。

返回202狀態碼的響應的目的是允許服務器接受其他過程的請求(例如某個每天只執行一次的基於批處理的操作),而不必讓客戶端一直保持與服務器的連接直到批處理操作全部完成。在接受請求處理並返回202狀態碼的響應應當在返回的實體中包含一些指示處理當前狀態的信息,以及指向處理狀態監視器或狀態預測的指針,以便用戶能夠估計操作是否已經完成。

203 Non-Authoritative Information

服務器已成功處理了請求,但返回的實體頭部元信息不是在原始服務器上有效的確定集合,而是來自本地或者第三方的拷貝。當前的信息可能是原始版本的子集或者超集。例如,包含資源的元數據可能導致原始服務器知道元信息的超集。使用此狀態碼不是必須的,而且只有在響應不使用此狀態碼便會返回200 OK的情況下才是合適的。

204 No Content

服務器成功處理了請求,但不需要返回任何實體內容,並且希望返回更新了的元信息。響應可能通過實體頭部的形式,返回新的或更新後的元信息。如果存在這些頭部信息,則應當與所請求的變量相呼應。

如果客戶端是瀏覽器的話,那麽用戶瀏覽器應保留發送了該請求的頁面,而不產生任何文檔視圖上的變化,即使按照規範新的或更新後的元信息應當被應用到用戶瀏覽器活動視圖中的文檔。

由於204響應被禁止包含任何消息體,因此它始終以消息頭後的第一個空行結尾。

205 Reset Content

服務器成功處理了請求,且沒有返回任何內容。但是與204響應不同,返回此狀態碼的響應要求請求者重置文檔視圖。該響應主要是被用於接受用戶輸入後,立即重置表單,以便用戶能夠輕松地開始另一次輸入。

204響應一樣,該響應也被禁止包含任何消息體,且以消息頭後的第一個空行結束。

206 Partial Content

服務器已經成功處理了部分 GET 請求。類似於 FlashGet 或者迅雷這類的 HTTP下載工具都是使用此類響應實現斷點續傳或者將一個大文檔分解為多個下載段同時下載。

該請求必須包含 Range 頭信息來指示客戶端希望得到的內容範圍,並且可能包含 If-Range 來作為請求條件。

響應必須包含如下的頭部域:

Content-Range 用以指示本次響應中返回的內容的範圍;如果是 Content-Type 為 multipart/byteranges 的多段下載,則每一 multipart 段中都應包含 Content-Range 域用以指示本段的內容範圍。假如響應中包含 Content-Length,那麽它的數值必須匹配它返回的內容範圍的真實字節數。

Date

ETag 和/或 Content-Location,假如同樣的請求本應該返回200響應。

Expires, Cache-Control,和/或 Vary,假如其值可能與之前相同變量的其他響應對應的值不同的話。

假如本響應請求使用了 If-Range 強緩存驗證,那麽本次響應不應該包含其他實體頭;假如本響應的請求使用了 If-Range 弱緩存驗證,那麽本次響應禁止包含其他實體頭;這避免了緩存的實體內容和更新了的實體頭信息之間的不一致。否則,本響應就應當包含所有本應該返回200響應中應當返回的所有實體頭部域。

假如 ETag 或 Last-Modified 頭部不能精確匹配的話,則客戶端緩存應禁止將206響應返回的內容與之前任何緩存過的內容組合在一起。

207 Multi-Status

WebDAV(RFC 2518)擴展的狀態碼,代表之後的消息體將是一個XML消息,並且可能依照之前子請求數量的不同,包含一系列獨立的響應代碼。

重定向(3字頭)

這類狀態碼代表需要客戶端采取進一步的操作才能完成請求。通常,這些狀態碼用來重定向,後續的請求地址(重定向目標)在本次響應的 Location 域中指明。

當且僅當後續的請求所使用的方法是 GET 或者 HEAD 時,用戶瀏覽器才可以在沒有用戶介入的情況下自動提交所需要的後續請求。客戶端應當自動監測無限循環重定向(例如:A->A,或者A->B->C->A),因為這會導致服務器和客戶端大量不必要的資源消耗。按照 HTTP/1.0 版規範的建議,瀏覽器不應自動訪問超過5次的重定向。

300 Multiple Choices

被請求的資源有一系列可供選擇的回饋信息,每個都有自己特定的地址和瀏覽器驅動的商議信息。用戶或瀏覽器能夠自行選擇一個首選的地址進行重定向。

除非這是一個 HEAD 請求,否則該響應應當包括一個資源特性及地址的列表的實體,以便用戶或瀏覽器從中選擇最合適的重定向地址。這個實體的格式由 Content-Type 定義的格式所決定。瀏覽器可能根據響應的格式以及瀏覽器自身能力,自動作出最合適的選擇。當然,RFC 2616規範並沒有規定這樣的自動選擇該如何進行。

如果服務器本身已經有了首選的回饋選擇,那麽在 Location 中應當指明這個回饋的 URI;瀏覽器可能會將這個 Location 值作為自動重定向的地址。此外,除非額外指定,否則這個響應也是可緩存的。

301 Moved Permanently

被請求的資源已永久移動到新位置,並且將來任何對此資源的引用都應該使用本響應返回的若幹個 URI 之一。如果可能,擁有鏈接編輯功能的客戶端應當自動把請求的地址修改為從服務器反饋回來的地址。除非額外指定,否則這個響應也是可緩存的。

新的永久性的URI 應當在響應的 Location 域中返回。除非這是一個 HEAD 請求,否則響應的實體中應當包含指向新的 URI 的超鏈接及簡短說明。

如果這不是一個 GET 或者 HEAD 請求,因此瀏覽器禁止自動進行重定向,除非得到用戶的確認,因為請求的條件可能因此發生變化。

註意:對於某些使用 HTTP/1.0 協議的瀏覽器,當它們發送的 POST 請求得到了一個301響應的話,接下來的重定向請求將會變成 GET 方式。

302 Move temporarily

請求的資源臨時從不同的 URI響應請求。由於這樣的重定向是臨時的,客戶端應當繼續向原有地址發送以後的請求。只有在Cache-Control或Expires中進行了指定的情況下,這個響應才是可緩存的。

上文有提及。

如果這不是一個 GET 或者 HEAD 請求,那麽瀏覽器禁止自動進行重定向,除非得到用戶的確認,因為請求的條件可能因此發生變化。

註意:雖然RFC 1945和RFC 2068規範不允許客戶端在重定向時改變請求的方法,但是很多現存的瀏覽器將302響應視作為303響應,並且使用 GET 方式訪問在 Location 中規定的 URI,而無視原先請求的方法。狀態碼303和307被添加了進來,用以明確服務器期待客戶端進行何種反應。

303 See Other

對應當前請求的響應可以在另一個 URI 上被找到,而且客戶端應當采用 GET 的方式訪問那個資源。這個方法的存在主要是為了允許由腳本激活的POST請求輸出重定向到一個新的資源。這個新的 URI 不是原始資源的替代引用。同時,303響應禁止被緩存。當然,第二個請求(重定向)可能被緩存。

註意:許多 HTTP/1.1 版以前的瀏覽器不能正確理解303狀態。如果需要考慮與這些瀏覽器之間的互動,302狀態碼應該可以勝任,因為大多數的瀏覽器處理302響應時的方式恰恰就是上述規範要求客戶端處理303響應時應當做的。

304 Not Modified

如果客戶端發送了一個帶條件的 GET 請求且該請求已被允許,而文檔的內容(自上次訪問以來或者根據請求的條件)並沒有改變,則服務器應當返回這個狀態碼。304響應禁止包含消息體,因此始終以消息頭後的第一個空行結尾。

該響應必須包含以下的頭信息:

Date,除非這個服務器沒有時鐘。假如沒有時鐘的服務器也遵守這些規則,那麽代理服務器以及客戶端可以自行將 Date 字段添加到接收到的響應頭中去(正如RFC 2068中規定的一樣),緩存機制將會正常工作。

ETag 和/或 Content-Location,假如同樣的請求本應返回200響應。

Expires, Cache-Control,和/或Vary,假如其值可能與之前相同變量的其他響應對應的值不同的話。

假如本響應請求使用了強緩存驗證,那麽本次響應不應該包含其他實體頭;否則(例如,某個帶條件的 GET 請求使用了弱緩存驗證),本次響應禁止包含其他實體頭;這避免了緩存了的實體內容和更新了的實體頭信息之間的不一致。

假如某個304響應指明了當前某個實體沒有緩存,那麽緩存系統必須忽視這個響應,並且重復發送不包含限制條件的請求。

假如接收到一個要求更新某個緩存條目的304響應,那麽緩存系統必須更新整個條目以反映所有在響應中被更新的字段的值。

305 Use Proxy

被請求的資源必須通過指定的代理才能被訪問。Location 域中將給出指定的代理所在的 URI 信息,接收者需要重復發送一個單獨的請求,通過這個代理才能訪問相應資源。只有原始服務器才能建立305響應。

註意:RFC 2068中沒有明確305響應是為了重定向一個單獨的請求,而且只能被原始服務器建立。忽視這些限制可能導致嚴重的安全後果。

306 Switch Proxy

在最新版的規範中,306狀態碼已經不再被使用。

307 Temporary Redirect

請求的資源臨時從不同的URI 響應請求。

新的臨時性的URI 應當在響應的 Location 域中返回。除非這是一個HEAD 請求,否則響應的實體中應當包含指向新的URI 的超鏈接及簡短說明。因為部分瀏覽器不能識別307響應,因此需要添加上述必要信息以便用戶能夠理解並向新的 URI 發出訪問請求。

如果這不是一個GET 或者 HEAD 請求,那麽瀏覽器禁止自動進行重定向,除非得到用戶的確認,因為請求的條件可能因此發生變化。

請求錯誤(4開頭)

這類的狀態碼代表了客戶端看起來可能發生了錯誤,妨礙了服務器的處理。除非響應的是一個 HEAD 請求,否則服務器就應該返回一個解釋當前錯誤狀況的實體,以及這是臨時的還是永久性的狀況。這些狀態碼適用於任何請求方法。瀏覽器應當向用戶顯示任何包含在此類錯誤響應中的實體內容。

如果錯誤發生時客戶端正在傳送數據,那麽使用TCP的服務器實現應當仔細確保在關閉客戶端與服務器之間的連接之前,客戶端已經收到了包含錯誤信息的數據包。如果客戶端在收到錯誤信息後繼續向服務器發送數據,服務器的TCP棧將向客戶端發送一個重置數據包,以清除該客戶端所有還未識別的輸入緩沖,以免這些數據被服務器上的應用程序讀取並幹擾後者。

400 Bad Request

語義有誤,當前請求無法被服務器理解。除非進行修改,否則客戶端不應該重復提交這個請求。

請求參數有誤。

401 Unauthorized

當前請求需要用戶驗證。該響應必須包含一個適用於被請求資源的 WWW-Authenticate 信息頭用以詢問用戶信息。客戶端可以重復提交一個包含恰當的 Authorization 頭信息的請求。如果當前請求已經包含了 Authorization 證書,那麽401響應代表著服務器驗證已經拒絕了那些證書。如果401響應包含了與前一個響應相同的身份驗證詢問,且瀏覽器已經至少嘗試了一次驗證,那麽瀏覽器應當向用戶展示響應中包含的實體信息,因為這個實體信息中可能包含了相關診斷信息。參見RFC 2617。

402 Payment Required

該狀態碼是為了將來可能的需求而預留的。

403 Forbidden

服務器已經理解請求,但是拒絕執行它。與401響應不同的是,身份驗證並不能提供任何幫助,而且這個請求也不應該被重復提交。如果這不是一個 HEAD 請求,而且服務器希望能夠講清楚為何請求不能被執行,那麽就應該在實體內描述拒絕的原因。當然服務器也可以返回一個404響應,假如它不希望讓客戶端獲得任何信息。

404 Not Found

請求失敗,請求所希望得到的資源未被在服務器上發現。沒有信息能夠告訴用戶這個狀況到底是暫時的還是永久的。假如服務器知道情況的話,應當使用410狀態碼來告知舊資源因為某些內部的配置機制問題,已經永久的不可用,而且沒有任何可以跳轉的地址。404這個狀態碼被廣泛應用於當服務器不想揭示到底為何請求被拒絕或者沒有其他適合的響應可用的情況下。出現這個錯誤的最有可能的原因是服務器端沒有這個頁面。

405 Method Not Allowed

請求行中指定的請求方法不能被用於請求相應的資源。該響應必須返回一個Allow 頭信息用以表示出當前資源能夠接受的請求方法的列表。

鑒於 PUT,DELETE 方法會對服務器上的資源進行寫操作,因而絕大部分的網頁服務器都不支持或者在默認配置下不允許上述請求方法,對於此類請求均會返回405錯誤。

406 Not Acceptable

請求的資源的內容特性無法滿足請求頭中的條件,因而無法生成響應實體。

除非這是一個 HEAD 請求,否則該響應就應當返回一個包含可以讓用戶或者瀏覽器從中選擇最合適的實體特性以及地址列表的實體。實體的格式由 Content-Type 頭中定義的媒體類型決定。瀏覽器可以根據格式及自身能力自行作出最佳選擇。但是,規範中並沒有定義任何作出此類自動選擇的標準。

407 Proxy Authentication Required

401響應類似,只不過客戶端必須在代理服務器上進行身份驗證。代理服務器必須返回一個 Proxy-Authenticate 用以進行身份詢問。客戶端可以返回一個 Proxy-Authorization 信息頭用以驗證。參見RFC 2617。

408 Request Timeout

請求超時。客戶端沒有在服務器預備等待的時間內完成一個請求的發送。客戶端可以隨時再次提交這一請求而無需進行任何更改。

409 Conflict

由於和被請求的資源的當前狀態之間存在沖突,請求無法完成。這個代碼只允許用在這樣的情況下才能被使用:用戶被認為能夠解決沖突,並且會重新提交新的請求。該響應應當包含足夠的信息以便用戶發現沖突的源頭。

沖突通常發生於對 PUT 請求的處理中。例如,在采用版本檢查的環境下,某次 PUT 提交的對特定資源的修改請求所附帶的版本信息與之前的某個(第三方)請求向沖突,那麽此時服務器就應該返回一個409錯誤,告知用戶請求無法完成。此時,響應實體中很可能會包含兩個沖突版本之間的差異比較,以便用戶重新提交歸並以後的新版本。

410 Gone

被請求的資源在服務器上已經不再可用,而且沒有任何已知的轉發地址。這樣的狀況應當被認為是永久性的。如果可能,擁有鏈接編輯功能的客戶端應當在獲得用戶許可後刪除所有指向這個地址的引用。如果服務器不知道或者無法確定這個狀況是否是永久的,那麽就應該使用404狀態碼。除非額外說明,否則這個響應是可緩存的。

410響應的目的主要是幫助網站管理員維護網站,通知用戶該資源已經不再可用,並且服務器擁有者希望所有指向這個資源的遠端連接也被刪除。這類事件在限時、增值服務中很普遍。同樣,410響應也被用於通知客戶端在當前服務器站點上,原本屬於某個個人的資源已經不再可用。當然,是否需要把所有永久不可用的資源標記為‘410 Gone‘,以及是否需要保持此標記多長時間,完全取決於服務器擁有者。

411 Length Required

服務器拒絕在沒有定義 Content-Length 頭的情況下接受請求。在添加了表明請求消息體長度的有效 Content-Length 頭之後,客戶端可以再次提交該請求。

412 Precondition Failed

服務器在驗證在請求的頭字段中給出先決條件時,沒能滿足其中的一個或多個。這個狀態碼允許客戶端在獲取資源時在請求的元信息(請求頭字段數據)中設置先決條件,以此避免該請求方法被應用到其希望的內容以外的資源上。

413 Request Entity Too Large

服務器拒絕處理當前請求,因為該請求提交的實體數據大小超過了服務器願意或者能夠處理的範圍。此種情況下,服務器可以關閉連接以免客戶端繼續發送此請求。

如果這個狀況是臨時的,服務器應當返回一個 Retry-After 的響應頭,以告知客戶端可以在多少時間以後重新嘗試。

414 Request-URI Too Long

請求的URI 長度超過了服務器能夠解釋的長度,因此服務器拒絕對該請求提供服務。這比較少見,通常的情況包括:

本應使用POST方法的表單提交變成了GET方法,導致查詢字符串(Query String)過長。

重定向URI “黑洞”,例如每次重定向把舊的 URI 作為新的 URI 的一部分,導致在若幹次重定向後 URI 超長。

客戶端正在嘗試利用某些服務器中存在的安全漏洞攻擊服務器。這類服務器使用固定長度的緩沖讀取或操作請求的 URI,當 GET 後的參數超過某個數值後,可能會產生緩沖區溢出,導致任意代碼被執行[1]。沒有此類漏洞的服務器,應當返回414狀態碼。

415 Unsupported Media Type

對於當前請求的方法和所請求的資源,請求中提交的實體並不是服務器中所支持的格式,因此請求被拒絕。

416 Requested Range Not Satisfiable

如果請求中包含了 Range 請求頭,並且 Range 中指定的任何數據範圍都與當前資源的可用範圍不重合,同時請求中又沒有定義 If-Range 請求頭,那麽服務器就應當返回416狀態碼。

假如 Range 使用的是字節範圍,那麽這種情況就是指請求指定的所有數據範圍的首字節位置都超過了當前資源的長度。服務器也應當在返回416狀態碼的同時,包含一個 Content-Range 實體頭,用以指明當前資源的長度。這個響應也被禁止使用 multipart/byteranges 作為其 Content-Type。

417 Expectation Failed

在請求頭 Expect 中指定的預期內容無法被服務器滿足,或者這個服務器是一個代理服務器,它有明顯的證據證明在當前路由的下一個節點上,Expect 的內容無法被滿足。

421There are too many connections from your internet address

從當前客戶端所在的IP地址到服務器的連接數超過了服務器許可的最大範圍。通常,這裏的IP地址指的是從服務器上看到的客戶端地址(比如用戶的網關或者代理服務器地址)。在這種情況下,連接數的計算可能涉及到不止一個終端用戶。

422 Unprocessable Entity

請求格式正確,但是由於含有語義錯誤,無法響應。(RFC 4918 WebDAV)

423 Locked

當前資源被鎖定。(RFC 4918 WebDAV)

424 Failed Dependency

由於之前的某個請求發生的錯誤,導致當前請求失敗,例如 PROPPATCH。(RFC 4918 WebDAV)

425 Unordered Collection

WebDav Advanced Collections 草案中定義,但是未出現在《WebDAV 順序集協議》(RFC 3658)中。

426 Upgrade Required

客戶端應當切換到TLS/1.0。(RFC 2817)

449 Retry With

由微軟擴展,代表請求應當在執行完適當的操作後進行重試。

服務器錯誤(5、6字頭)編輯

這類狀態碼代表了服務器在處理請求的過程中有錯誤或者異常狀態發生,也有可能是服務器意識到以當前的軟硬件資源無法完成對請求的處理。除非這是一個HEAD 請求,否則服務器應當包含一個解釋當前錯誤狀態以及這個狀況是臨時的還是永久的解釋信息實體。瀏覽器應當向用戶展示任何在當前響應中被包含的實體。

這些狀態碼適用於任何響應方法。

500 Internal Server Error

服務器遇到了一個未曾預料的狀況,導致了它無法完成對請求的處理。一般來說,這個問題都會在服務器端的源代碼出現錯誤時出現。

501 Not Implemented

服務器不支持當前請求所需要的某個功能。當服務器無法識別請求的方法,並且無法支持其對任何資源的請求。

502 Bad Gateway

作為網關或者代理工作的服務器嘗試執行請求時,從上遊服務器接收到無效的響應。

503 Service Unavailable

由於臨時的服務器維護或者過載,服務器當前無法處理請求。這個狀況是臨時的,並且將在一段時間以後恢復。如果能夠預計延遲時間,那麽響應中可以包含一個 Retry-After 頭用以標明這個延遲時間。如果沒有給出這個 Retry-After 信息,那麽客戶端應當以處理500響應的方式處理它。

註意:503狀態碼的存在並不意味著服務器在過載的時候必須使用它。某些服務器只不過是希望拒絕客戶端的連接。

504 Gateway Timeout

作為網關或者代理工作的服務器嘗試執行請求時,未能及時從上遊服務器(URI標識出的服務器,例如HTTP、FTP、LDAP)或者輔助服務器(例如DNS)收到響應。

註意:某些代理服務器在DNS查詢超時時會返回400或者500錯誤

505 HTTP Version Not Supported

服務器不支持,或者拒絕支持在請求中使用的 HTTP 版本。這暗示著服務器不能或不願使用與客戶端相同的版本。響應中應當包含一個描述了為何版本不被支持以及服務器支持哪些協議的實體。

506 Variant Also Negotiates

由《透明內容協商協議》(RFC 2295)擴展,代表服務器存在內部配置錯誤:被請求的協商變元資源被配置為在透明內容協商中使用自己,因此在一個協商處理中不是一個合適的重點。

507 Insufficient Storage

服務器無法存儲完成請求所必須的內容。這個狀況被認為是臨時的。WebDAV (RFC 4918)

509 Bandwidth Limit Exceeded

服務器達到帶寬限制。這不是一個官方的狀態碼,但是仍被廣泛使用。

510 Not Extended

獲取資源所需要的策略並沒有沒滿足。(RFC 2774)

600 Unparseable Response Headers

源站沒有返回響應頭部,只返回實體內容

API的HTTP Status Code