Как обрабатывать ответы об ошибках

В этом руководстве рассказывается, как обрабатывать ошибки, возвращаемые 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).

Примеры ответов с ошибками

Ниже приведен пример структуры ошибки 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, то URL, на который он указывает, может быть заменен на URL более новой страницы документации без предварительного уведомления. Однако, как упоминалось ранее, значение details.metadata.REASON стабильно.

Рекомендации

Следуйте приведенным ниже рекомендациям, чтобы обеспечить корректную обработку ошибок.

Используйте details.metadata.REASON для логики

Чтобы определить причину ошибки, всегда используйте конкретный объект REASON внутри карты metadata. Не полагайтесь только на код статуса HTTP, поскольку один и тот же код может соответствовать нескольким ошибкам.

Не анализировать сообщение об ошибке

Как отмечалось в разделе о стабильности, поле message предназначено для чтения человеком. Если вам нужна динамическая информация (например, о том, какое поле было недействительным), извлеките ее из карты metadata, используя стабильные ключи, такие как FIELD_LOCATION, VARIABLE_NAME.

Как реализовать экспоненциальную выдержку

Если ошибки указывают на временную недоступность или ограничение частоты запросов, реализуйте стратегию экспоненциальной выдержки. Это означает, что перед повторной попыткой нужно подождать некоторое время, увеличивая его после каждой последующей неудачи.

  • quota/request_rate_too_high – вы превысили минутную квоту для определенной группы квот. Снизьте частоту запросов.
  • internal_error – обычно это временные ошибки. Повторите попытку с экспоненциальной выдержкой.

Как связаться со службой поддержки Merchant API

Если вам нужно обратиться в службу поддержки Merchant API по поводу определенной ошибки, укажите в запросе следующую информацию:

  1. Точный ответ об ошибке.
  2. Название метода API.
  3. Полезная нагрузка запроса.
  4. Временные метки или диапазон дат, когда был вызван метод и получены ошибки.
Назад
Track usage metrics
Далее
Error messages