狀態代碼和錯誤代碼是指響應頭中的代碼號，用於指示響應的常規分類，例如，請求是否成功（200），是否導致服務器錯誤（500），是否存在授權問題（403），等等。標準狀態代碼通常不需要太多文檔，但是特定於您的API的自定義狀態和錯誤代碼則需要。錯誤代碼特別有助於解決不良請求。
目錄
- curl標頭中的狀態碼示例
- 列出HTTP響應和錯誤碼的位置
- 在哪裡獲取狀態和錯誤碼
- 如何列出狀態碼
- 狀態/錯誤代碼可以幫助進行故障排除
- 狀態和錯誤碼示例Context.ioTwitterMailchimpFlickr
- 具有狀態和錯誤代碼的活動
curl標頭中的狀態碼示例
狀態碼未出現在響應正文中。它們顯示在響應標題中，默認情況下您可能看不到。還記得您在“curl調用方法”中提交了curl調用嗎？要獲取響應頭，請在curl請求中添加--include或-i。如果您只想在響應中返回響應標頭（而不要返回其他任何內容），請大寫-I，如下所示：
<code>curl -I -X GET "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial"/<code>
響應頭如下所示：
<code>HTTP/1.1 200 OKServer: openrestyDate: Thu, 06 Dec 2018 22:58:41 GMTContent-Type: application/json; charset=utf-8Content-Length: 446Connection: keep-aliveX-Cache-Key: /data/2.5/weather?units=imperial&zip=95050Access-Control-Allow-Origin: *Access-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST/<code>
第一行HTTP / 1.1 200 OK告訴我們請求的狀態（200）。大多數REST API都遵循響應頭的標準協議。例如，200不僅僅是OpenWeatherMap API開發人員確定的任意代碼。200是用於成功HTTP請求的通用代碼。（如果您更改方法，則會獲得其他狀態代碼。）
有了GET請求，很容易判斷請求是否成功，因為您會獲得預期的響應。但是，假設您要進行POST，PUT或DELETE調用，那麼您將在其中更改資源中包含的數據。您如何知道API是否成功處理並接收了請求？響應標頭中的HTTP響應代碼將指示操作是否成功。HTTP狀態代碼只是較長消息的縮寫。
狀態代碼非常微妙，但是當開發人員使用API時，這些代碼可能是開發人員擁有的唯一“接口”。如果您可以
狀態碼通常不提供信息，編寫得很差，並且很少或沒有向用戶傳達有用的信息來克服該錯誤。最終，狀態碼應幫助用戶從錯誤中恢復。
您可以在此處查看常見的REST API狀態代碼列表，並在此處查看HTTP狀態代碼的常規列表。儘管最好包含一些標準狀態代碼，但是不需要全面記錄所有標準狀態代碼，尤其是在您的API很少觸發的情況下。
列出HTTP響應和錯誤碼的位置
大多數API應該有一個通用頁面，其中列出了整個API的響應和錯誤代碼。一個單獨的頁面列出了狀態代碼（而不是在每個端點中包括這些狀態代碼），使您可以更詳細地擴展每個代碼，而不會佔用其他文檔。它還減少了冗餘和信息過載感。
另一方面，如果某些端點比其他端點更容易觸發某些狀態和錯誤代碼，則在相同的API參考頁面上突出顯示這些狀態和錯誤代碼是有意義的。一種策略可能是引起注意特定端點的任何特別相關的狀態或錯誤代碼，然後鏈接到集中的“響應和狀態代碼”頁面以獲取完整信息。
在哪裡獲取狀態和錯誤代碼
在記錄API時，狀態代碼和錯誤代碼可能並不明顯。您可能需要向開發人員索要API獨有的所有狀態和錯誤代碼的列表。有時，開發人員會直接在編程代碼中對這些狀態和錯誤代碼進行硬編碼，而沒有簡單的方法來向您提供完整的列表（這也使本地化成為問題）。結果，您可能需要嘗試一下以找出所有代碼。
具體來說，您可能需要嘗試破壞API才能查看所有潛在的錯誤代碼。例如，如果您超出了特定呼叫的速率限制，則API可能會返回特殊錯誤或狀態代碼。您尤其需要記錄此自定義代碼。API中的疑難解答部分可能會特別使用錯誤代碼。
如何列出狀態碼
您可以在基本表或定義列表中列出狀態和錯誤代碼，如下所示：
狀態/錯誤代碼可以幫助進行故障排除
狀態和錯誤代碼在進行故障排除時特別有用。因此，您可以將這些錯誤代碼視為故障排除部分的補充。幾乎所有的文檔集都可以從故障排除一節中受益。
在故障排除主題中，您記錄了當用戶走開快樂的道路並在黑暗的森林中迷路時發生的情況。狀態代碼就像照明不佳的步道標誌一樣，可以幫助用戶回到正確的道路上。
有關疑難解答的一節可能列出與以下情況有關的錯誤消息：
- 使用了錯誤的API密鑰
- 使用了無效的API密鑰
- 參數不適合數據類型
- API引發異常
- 沒有數據可返回的資源
- 已超出速率限制
- 參數超出了可接受的最大值和最小值範圍
- 端點缺少必需的參數
儘可能在文檔中記錄錯誤的確切文本，以便在搜索時輕鬆顯示該錯誤。
狀態和錯誤代碼示例
以下是API文檔中的一些示例狀態和錯誤代碼頁。
Context.io
Context.io狀態和錯誤代碼
Clearbit不僅記錄了標準狀態碼，而且還描述了其API返回的唯一參數。大多數開發人員可能會熟悉200、400和500的代碼，因此這些代碼不需要太多解釋性的細節。但是，如果您的API具有唯一的代碼，請確保充分描述它們。
Twitter狀態和錯誤代碼
藉助Twitter的狀態代碼文檔，他們不僅可以描述代碼和狀態，還可以提供有用的故障排除信息，從而可能有助於錯誤恢復。例如，對於500錯誤，作者不只是說狀態是指服務中斷，他們還解釋說：“這通常是暫時的錯誤，例如在高負載情況下，或者端點暫時有問題。如果其他人遇到類似問題，請登錄開發者論壇，或者稍後再試。”
這種有用的信息是技術作者應針對狀態代碼（至少對於那些指示問題的代碼）的目標。
Mailchimp
Mailchimp狀態和錯誤代碼
Mailchimp提供了錯誤消息的可讀且友好的描述。例如，對於403錯誤，Mailchimp不僅僅是寫“ Forbidden”，還解釋了為什麼您可能會收到Forbidden代碼的原因。使用Mailchimp，有幾種類型的403錯誤。您的請求可能由於用戶帳戶被禁用或對錯誤的數據中心的請求而被禁止。對於“ WrongDataCenter”錯誤，Mailchimp指出“它通常與配置錯誤的庫相關聯”，並且它們鏈接到有關數據中心的更多信息。這是對用戶有用的錯誤代碼文檔。
Flickr
Flickr的狀態和錯誤代碼
使用Flickr，“響應代碼”部分嵌入在每個API參考主題中。因此，描述簡短。在每個主題中嵌入響應代碼會使錯誤代碼更明顯，但在某些方面卻沒有太大幫助。因為它嵌入在每個API主題中，所以有關錯誤代碼的描述必須簡短，否則內容將使端點請求信息不堪重負。
相比之下，列出錯誤代碼的獨立頁面使您可以在不排擠其他文檔的情況下更詳細地擴展每個代碼。獨立頁面還可以減少冗餘並減少大量信息（只是重複的信息）的顯示。
如果某些端點比其他端點更容易觸發某些狀態和錯誤代碼，則在其相關的API參考頁上突出顯示這些狀態和錯誤代碼是有意義的。建議您注意端點頁面上任何特別相關的狀態或錯誤代碼，然後鏈接到集中頁面以獲取完整信息。
具有狀態和錯誤代碼的活動
使用您確定的開源項目，確定狀態和錯誤代碼信息。回答以下問題：
- 項目是否描述狀態和錯誤代碼？狀態和錯誤代碼信息在文檔上下文中位於何處？作為獨立主題？在每個端點之下？別的地方？
- API是否具有任何唯一的狀態和錯誤代碼？
- 錯誤代碼是否可以幫助用戶從錯誤中恢復？
- 向其中一個端點發出請求。然後有意地更改參數，以使其無效。響應中返回什麼狀態碼？是否記錄了此狀態碼？
閱讀更多 沙場點兵見穹蒼 的文章
