當一個 API 請求沒能成功的時候，客戶端最好能收到一個正確的 HTTP 錯誤狀態，例如 409 或 500，這會是一個好的開始。不幸的是，盡管 400 Bad Request 可能就足夠讓我們知道錯誤出在哪里，但常見的情況是我們沒有充足的信息來理解或解決實際遇到的問題。

許多 API 會在響應正文中為你提供更多細節，但令人遺憾的是，每個 API 都有自己的定制風格，不同的 API，甚至在各個端點使用的報告樣式都不一樣。這就需要定制的邏輯或者人工干預才能理解報告的內容。

但這種情況并非無可避免。先不用急著否定我。試著想象一個更好的世界，其中每個 API 都以相同的標準格式返回錯誤信息。

我們可以用一致的標識符來識別各種類型的錯誤，并能在任何地方輕松獲得清晰的描述和元數據。你的通用 HTTP 客戶端可以自動為任何錯誤提供詳盡細節，你的客戶端錯誤處理機制則能輕松可靠地過濾出你所關心的特定錯誤，并且你能使用單組共享邏輯來處理多種 API 的常見錯誤。

IETF 提出的 RFC 7807 標準希望定義一個 HTTP API 錯誤響應的標準格式，從而實現上述目標。它已經開始在現實世界中得到應用了。人們可以很容易地用它來支持現有的 API 和客戶端，對于構建或使用 HTTP API 的人來說，這個標準值得關注。

標準錯誤格式為什么這么有用？

請不要這樣做

談這個問題前，讓我們先退一步思考問題。HTTP 的一個關鍵特性是標準的響應狀態代碼，例如 200 或 404。正確使用這些代碼可確保客戶端自動理解響應的總體狀態，并根據對應狀態采取適當措施。

狀態代碼對錯誤處理來說特別有用。當請求收到意外的 500 狀態時，幾乎所有標準的 HTTP 客戶端都會自動為你拋出一個錯誤，并不需要自定義規則來解析和解釋各處的所有響應，從而確保意外錯誤能被可靠地報告，并可以在任何位置輕松處理。

這是很好的機制，但它也有很大的局限性。

實際上，一個 HTTP 400 響應可能表示以下任何一種情況：

你的請求格式錯誤，無法解析
你的請求意外為空，或缺少一些必需的參數
你的請求有效，但仍然模棱兩可，因此無法處理
你的請求有效，但由于服務器錯誤，服務器認為請求無效
你的請求有效，但請求的是完全不可能的內容
你的請求已啟動，但服務器拒絕了你提供的參數值
你的請求已啟動，但服務器拒絕了你提供的每個參數值
你的請求已啟動，但你的銀行拒絕了其中包含的銀行卡資料
你的請求完成了一項購買操作，但請求的其他部分在稍后階段被拒絕

這些全是錯誤，看起來都是由一個“壞”請求觸發的 400 錯誤，但它們的內容卻大相徑庭。

狀態代碼可幫助我們區分錯誤和成功狀態，但沒法區分得太細致。因此，HTTP 客戶端庫不能在拋出的錯誤中包含任何有用的細節，每個 API 客戶端都必須編寫自定義的處理機制來解析每個失敗的響應，并自行找出可能的原因和下一步應該做的操作。

如果失敗的 HTTP 請求自動拋出的異常消息不僅僅是HTTP Error: 400 Bad Request，而是 Credit card number is not valid，這樣豈不更好？

只要錯誤有一套標準格式，上面提到的每個錯誤就都可以有自己的唯一標識符，并包含標準化的說明內容和指向更多細節的鏈接。好處是：

通用工具可以為你解析和解釋錯誤的詳細信息，而無需事先了解任何與 API 相關的信息。
API 能更安全地發起錯誤響應，因為它知道這些錯誤類型標識符意味著即使解釋消息發生了更改，客戶端也會一直按同一種理解方式識別錯誤。
自定義 API 客戶端可以檢查錯誤類型以輕松處理特定情況，所有操作都以一種標準方式進行，適用于你所使用的每個 API，而無需從頭開始編寫 API 包裝程序，也用不著每次都和 API 文檔大戰三百回合。

提案的錯誤格式長什么樣？

為此，RFC7807 提出了一組用于返回錯誤的標準字段，以及兩種將其格式化為 JSON 或 XML 的內容類型。

格式如下：

{
    "type": "https://example.com/probs/out-of-credit",
    "title": "You do not have enough credit.",
    "detail": "Your current balance is 30, but that costs 50.",
    "instance": "/account/12345/transactions/abc"
}

對于 XML 的等效格式：

<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:rfc:7807">
    <type>https://example.com/probs/out-of-credit</type>
    <title>You do not have enough credit.</title>
    <detail>Your current balance is 30, but that costs 50.</detail>
    <instance>/account/12345/transactions/abc</instance>
</problem>

這些 RFC 為此定義了兩種新的對應內容類型：Application/problem+json或application/problem+xml。返回錯誤的 HTTP 響應應在其Content-Type響應標頭中包含適當的內容類型，并且客戶端可以檢查該標頭以確認格式。

這個示例包括規范定義的一些標準化字段。完整列表是如下：

type：標識錯誤類型的 URI。在瀏覽器中加載這個 URI 應該轉向這個錯誤的文檔，但這不是嚴格要求的。此字段可用于識別錯誤類。理論上講，將來站點甚至可以為常見情況共享標準化的錯誤 URI，以使通用客戶端自動檢測到它們。
title：錯誤的簡短可讀摘要。這是明確的指引，客戶端必須使用 type 作為識別 API 錯誤類型的主要方式。
detail：較長的人類可讀解釋，帶有完整的錯誤詳細信息。
status：錯誤使用的 HTTP 狀態代碼。它必須與實際狀態匹配，但可以包含在這里的 body 中以便參考。
instance：標識該特定故障實例的 URI。它可以作為發生的這個錯誤的 ID，和/或到特定故障更多詳細信息的鏈接，例如顯示失敗的信用卡交易細節的頁面。

所有這些字段都是可選的（不過type是強烈建議使用的）。內容類型允許自由包含其他數據，只要它們不與這些字段沖突即可，因此你也可以在此處添加自己的錯誤元數據，并包含所需的其他任何數據。實例 URI 和類型 URI 都可以是絕對 URI，也可以是相對 URI。

這里的思想是：