处理错误响应

本指南介绍了如何处理 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 对象提供有关错误的稳定结构化数据：

  • 网域：错误的逻辑分组，通常为 merchantapi.googleapis.com。
  • 元数据：与错误相关的动态值映射。其中包括：
    • 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. 调用该方法并收到错误的时间戳或时间范围