В этом руководстве объясняется, как обрабатывать ошибки, возвращаемые API продавца. Понимание структуры и стабильности ответа об ошибке имеет решающее значение для создания надежных интеграций, которые могут автоматически восстанавливаться после сбоев или предоставлять пользователям полезную обратную связь.
Обзор
Когда запрос к API продавца завершается неудачей, API возвращает стандартный HTTP-код состояния ( 4xx или 5xx ) и тело ответа в формате JSON, содержащее подробную информацию об ошибке. API продавца соответствует стандарту AIP-193 для предоставления подробной информации об ошибках, предоставляя машиночитаемые данные, которые позволяют вашему приложению программно обрабатывать конкретные сценарии ошибок.
Структура ответа об ошибке
Ответ об ошибке представляет собой JSON-объект, содержащий стандартные поля, такие как code , message и status . Важно отметить, что он также включает массив details . Для программной обработки ошибок следует искать в массиве details объект, у которого @type равен type.googleapis.com/google.rpc.ErrorInfo .
Объект ErrorInfo предоставляет стабильные, структурированные данные об ошибке:
- Домен : логическая группировка ошибки, обычно
merchantapi.googleapis.com. - Метаданные : Карта динамических значений, связанных с ошибкой. Включает в себя:
- ПРИЧИНА : Конкретный, стабильный идентификатор точной ошибки (например,
INVALID_NAME_PART_NOT_NUMBER,PERMISSION_DENIED_ACCOUNTS). Это поле всегда присутствует. Используйте это поле для более точной обработки ошибок в логике вашего приложения. - HELP_CENTER_LINK : Предоставляет дополнительную информацию и инструкции по устранению проблемы. Это поле присутствует не для всех ошибок, но мы планируем со временем расширить его охват для тех ошибок, где может потребоваться дополнительная информация.
- Другие динамические поля : другие ключи, предоставляющие контекст, например, имя недопустимого поля (
FIELD_LOCATION) или значение, вызвавшее ошибку (FIELD_VALUE).
- ПРИЧИНА : Конкретный, стабильный идентификатор точной ошибки (например,
Примеры ответов об ошибках
Приведенный ниже JSON демонстрирует структуру ошибки 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.metadatakeys : Ключи в карте метаданных (например,FIELD_LOCATION,ACCOUNT_IDS) являются стабильными. -
code: Высокоуровневый код состояния HTTP (например,400,401,503) является стабильным.
-
Нестабильные поля:
-
message: Удобочитаемое сообщение об ошибке нестабильно . Оно предназначено только для отладки разработчиками. Не пишите код, который анализирует или полагается на текстовое содержимое поляmessage, поскольку оно может изменяться без предварительного уведомления для повышения ясности или добавления контекста. - Значения
details.metadata: Хотя сами ключи стабильны, значения информационных ключей могут изменяться. Например, если указан ключHELP_CENTER_LINK, конкретный URL-адрес, на который он указывает, может быть обновлен до более новой страницы документации без предварительного уведомления. Однако, как упоминалось ранее, значениеdetails.metadata.REASONстабильно.
-
Передовые методы
Следуйте этим рекомендациям, чтобы ваша интеграция корректно обрабатывала ошибки.
Используйте details.metadata.REASON для логики.
Для определения причины ошибки всегда используйте конкретную REASON из карты metadata . Не полагайтесь только на код состояния HTTP, поскольку несколько ошибок могут иметь один и тот же код состояния.
Не анализируйте сообщение об ошибке.
Как указано в разделе о стабильности, поле message предназначено для восприятия человеком. Если вам нужна динамическая информация (например, какое поле было недействительным), извлеките ее из карты metadata , используя стабильные ключи, такие как FIELD_LOCATION , VARIABLE_NAME .
Реализуйте экспоненциальную задержку.
При ошибках, указывающих на временную недоступность или ограничение скорости, следует применять стратегию экспоненциальной задержки. Это означает ожидание в течение короткого периода времени перед повторной попыткой и увеличение времени ожидания с каждой последующей неудачей.
-
quota/request_rate_too_high: Эта ошибка указывает на то, что вы превысили свою минутную квоту для определенной группы квот. Снизьте скорость запросов. -
internal_error: Обычно это временные ошибки. Повторите попытку с экспоненциальной задержкой. Примечание: Еслиinternal_errorсохраняется после нескольких повторных попыток с задержкой, см. раздел «Как связаться со службой поддержки Merchant API» .
Как связаться со службой поддержки Merchant API
Если вам необходимо связаться со службой поддержки Merchant API по поводу конкретной ошибки, укажите в своем запросе следующую информацию:
- Точный ответ об ошибке получен.
- Название метода API
- Полезная нагрузка запроса
- Временные метки или временной диапазон, в течение которого был вызван метод и получены ошибки.