API網關如何發展：更輕、更智能、云原生
你可能也喜歡這些API文章!
看看這比簡單的 4xx 或 5xx 代碼有用多少，您只能猜測哪里出了問題？ Stripe API 的錯誤消息不僅告訴您出了什么問題，而且還告訴您如何修復它。
Merge API是一種用于通過單一來源整合許多不同 API 的 API。他們有額外的動力來提供高質量的錯誤消息。合并 API 從多個來源接收API 錯誤，然后需要以一致且可理解的方式返回這些錯誤。
例如，當您查詢 Merge API 查找不存在的資源時，您會收到以下響應：
{
"status": 400,
"error": "Not Found",
"message": "The requested resource was not found on this server.",
"path": "/api/users/5678",
"timestamp": "2024-10-20T12:34:56Z"
}通過包含路徑，用戶可以仔細檢查以確保他們正在查詢正確的端點。返回時間戳使得 API 錯誤消息也有助于調試和日志記錄，從而允許用戶檢查特定資源在特定時間是否不可用。
Instagram 每月擁有超過 20 億活躍用戶。他們更有理由擁有任何人都可以輕松理解的深入、有用的 API 錯誤消息。當用戶對太大而無法下載的圖像發出 API 請求時，他們會看到以下響應：
{
"error":
{
"message": "The image size is too large.",
"type": "OAuthException",
"code": 36000,
"error_subcode": 2207004,
"is_transient": false,
"error_user_title": "Image size too large",
"error_user_msg": "The image is too large to download. It should be less than 8 MiB.",
"fbtrace_id": "A6LJylpZRKw2xKLFsAP-cJh"
}
}這在某種程度上違背了我們關于不需要說明手冊來理解 API 錯誤消息的評論，但它仍然是自我描述的。該消息詳細說明了問題所在。錯誤代碼和子代碼提供了有關問題以及如何修復它的更多詳細信息。這種方法對于執行許多不同操作的 API 很有幫助，因為子代碼可用于識別未按應有方式運行的特定函數。
Salesforce API是目前 Postman 上最受歡迎的集合，說明了這個強大的銷售和營銷平臺有多么受歡迎。由于有如此多的用戶通過 API 執行如此多的財務敏感業務，因此需要詳細、有用的 API 錯誤消息。
Salesforce API 并不令人失望，有 14 條獨特的 4xx 錯誤消息和 3 條 5xx 消息。是的，他們的許多錯誤消息都非常簡單，但是無論如何，有這么多不同的錯誤消息可以讓用戶確切地知道出了什么問題。例如，在登錄時提供錯誤的憑據會返回一個簡單的401錯誤：
{"error_description": "Client authentication failed", "error": "invalid_client"}忽略正確格式化查詢可能會返回428錯誤，而是：
{"error_description": "The request wasn't executed because it wasn't conditional. Add one of the Conditional Request Headers, such as If-Match, to the request and resubmit it.", "error": "PRECONDITION_REQUIRED"}我們將用另一個連接器 API 來完成我們的列表，因為它們具有如此廣泛的功能并且需要如此具體。 Reltio API是一套用于將數據集成到一個平臺的工具，很像 Merge API。不過，Reltio 更深入，讓您可以通過一系列 API 執行 CRUD。
Integrate API 是最令人印象深刻的，因為它包含針對各種最流行的 API、工具和資源的專用功能。每個連接器都有自己的錯誤代碼，正如您在 Salesforce 集成中看到的那樣：
Error 1020: Invalid request, tenant {tenantId} is forbidden for current user當你在Reltio API文檔中查看這個錯誤時，它也給了你一個解決方案。這打破了自我描述的規則，但它可以通過它所使用的廣泛工具來彌補。
API 不僅限于返回簡單的503錯誤。由于能夠提供 JSON 或 XML 等資源，因此可以返回有關 API 運行情況的詳細文檔。正如 Fielding 所設想的那樣，API 錯誤消息首先是 API 潛力的最佳體現之一，使用戶無需查閱 API 文檔。 API 錯誤消息是提升開發人員體驗和最終客戶體驗的最快、最簡單且成本最低的方法之一。
當然，平衡效率和安全性很重要。 API 錯誤消息暴露了太多信息。對于 API 開發人員來說，在編寫 API 錯誤消息時牢記API 安全最佳實踐非常重要，因為敏感信息可能會導致未經授權的用戶獲得網絡訪問權限。信息和安全性之間的正確平衡可以為參與 API 的每個人提供更好的體驗。
原文鏈接：https://nordicapis.com/5-real-world-examples-of-great-api-error-messages/
