5个优秀API错误消息的真实示例

使用 API 时，您不需要拿出说明手册来了解每个响应试图告诉您什么。 API 及其错误响应应该是人类可以理解的，也是机器可读的，这意味着它们应该是 Roy Fielding 所定义的自我描述性。没有理由需要将 API 限制为通用 HTTP 请求。

很容易想到不要对API 错误处理做什么。但你应该做什么呢？我们检查了各种不同的公共 API，以找到一些最佳的实际 API 错误响应。下面的示例应该可以让您了解自己的 API 错误消息的模型。

1. Stripe API

Stripe API 是市场上最流行的支付处理 API之一。这使得值得评估一下他们如何处理 API 错误消息。 Stripe API 不会让人失望，因为它的 API 错误消息非常有用且详细。

例如，如果您发出 API 请求以查看对没有 API 密钥的账户产生的所有费用，您将收到以下响应。

{

  "error": {

    "message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY'). See https://stripe.com/docs/api#authentication for details, or we can help at https://support.stripe.com/.",

    "type": "invalid_request_error"

  }

}

看看这比简单的 4xx 或 5xx 代码有用多少，您只能猜测哪里出了问题？ Stripe API 的错误消息不仅告诉您出了什么问题，而且还告诉您如何修复它。

2. Merge 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 错误消息也有助于调试和日志记录，从而允许用户检查特定资源在特定时间是否不可用。

3.Instagram 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 很有帮助，因为子代码可用于识别未按应有方式运行的特定函数。

4. Salesforce 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"}

5.Reltio API

我们将用另一个连接器 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 错误消息的最后一句话

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/