处理错误响应

本指南介绍了如何处理 Merchant API 返回的错误。了解错误响应结构和稳定性对于构建稳健的集成至关重要，这些集成可以自动从故障中恢复，或向用户提供有意义的反馈。

概览

当 Merchant API 请求失败时，该 API 会返回标准 HTTP 状态代码（4xx 或 5xx）和一个 JSON 响应正文，其中包含有关错误的详细信息。Merchant API 遵循 AIP-193 标准来提供 错误详细信息，提供机器可读的信息，让您的 应用能够以程序化方式处理特定的错误场景。

错误响应结构

错误响应是一个 JSON 对象，其中包含 code、 message 和 status 等标准字段。至关重要的是，它还包含一个 details 数组。如需以编程方式处理错误，您应在 details 中查找 @type 为 type.googleapis.com/google.rpc.ErrorInfo 的对象。

此 ErrorInfo 对象提供有关错误的稳定结构化数据：

  • domain：错误的逻辑分组，通常为 merchantapi.googleapis.com。
  • metadata：与错误相关的动态值映射。其中包括：
    • REASON：特定于确切错误的稳定标识符（例如 INVALID_NAME_PART_NOT_NUMBER、PERMISSION_DENIED_ACCOUNTS）。此 字段始终存在。在应用逻辑中使用此字段可进行精细的错误处理。
    • HELP_CENTER_LINK：提供额外的背景信息和说明来 解决问题。并非所有错误都包含此字段，但我们计划随着时间的推移扩大其覆盖范围，以便为可能需要更多背景信息的错误提供此字段。
    • 其他动态字段：提供背景信息的其他键，例如无效字段的名称 (FIELD_LOCATION) 或导致错误的 值 (FIELD_VALUE)。

错误响应示例

以下 JSON 展示了 Merchant API 错误的结构，其中资源名称格式不正确。

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

以下是身份验证错误的示例：

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

错误字段的稳定性

编写错误处理逻辑时，务必了解哪些字段可以安全地依赖，哪些字段可能会发生变化。

  • 稳定字段：

  • details.metadata.REASON：特定错误标识符。您应依赖此字段来确定应用的控制流逻辑。

    • details.metadata 键 ：元数据映射中的键（例如 FIELD_LOCATION、ACCOUNT_IDS）是稳定的。
    • code：高级 HTTP 状态代码（例如 400、401、503） 是稳定的。

  • 不稳定字段：

    • message：人类可读的错误消息不 稳定。它仅供开发者调试使用。请勿编写解析 或依赖于 message 字段文本内容的代码，因为该字段可能会在不另行通知的情况下发生变化 ，以提高清晰度或添加背景信息。
    • details.metadata 值：虽然 键是稳定的，但信息键的 值 可能会发生变化。例如，如果提供了 HELP_CENTER_LINK 键，它指向的特定网址可能会更新为较新的文档页面，而不会事先通知。不过，如前所述，details.metadata.REASON 的值是稳定的。

最佳实践

请遵循以下最佳实践，确保您的集成能够妥善处理错误。

使用 details.metadata.REASON 进行逻辑处理

始终使用 metadata 映射中的特定 REASON 来确定错误的原因。不要仅依赖 HTTP 状态代码，因为多个错误可能共享同一状态代码。

不要解析错误消息

如稳定性部分所述，message 字段供人类使用。 如果您需要动态信息（例如哪个字段无效），请使用 FIELD_LOCATION、VARIABLE_NAME 等稳定键从 metadata 映射中提取该信息。

实现指数退避算法

对于指示暂时不可用或速率限制的错误，请实现指数退避算法。这意味着在重试之前等待一小段时间，并随着每次后续失败而增加等待时间。

  • quota/request_rate_too_high：此错误表示您已超出特定配额组的分钟 配额。请降低请求速率。
  • internal_error：这些错误通常是暂时性的。请使用指数退避算法重试。注意：如果在多次使用 退避算法重试后 internal_error 仍然存在，请参阅如何与 Merchant API 支持团队联系。

如何与 Merchant API 支持团队联系

如果您需要就 特定错误与 Merchant API 支持团队联系，请在请求中提供以下信息：

  1. 收到的确切错误响应
  2. API 方法名称
  3. 请求载荷
  4. 调用该方法和收到错误时的时间戳或时间范围