Коды ошибок

На этой странице описаны канонические коды ошибок, которые необходимо возвращать в ответах API при интеграции с Google с использованием протокола Universal Commerce Protocol (UCP). Единые коды ошибок обеспечивают четкую коммуникацию и помогают Google корректно обрабатывать различные сценарии.

При возникновении бизнес-ошибки ваш API должен возвращать ответное сообщение, содержащее соответствующий code из таблицы. Для некоторых кодов ошибок рекомендуется использовать определенную структуру JSON для массива messages в ответе. Примеры приведены в разделе « Примеры кодов ошибок» под таблицей. В этих примерах следует использовать поле path для предоставления более подробной информации о местоположении ошибки в объекте запроса или ответа.

Обработка ошибок

Способ сообщения об ошибках зависит от типа ошибки:

• Ошибки протокола/сервера:

  • Для таких проблем, как некорректные запросы, сбои аутентификации или недоступность сервера, используйте стандартные коды состояния HTTP (например, 4xx для ошибок клиента, 5xx для ошибок сервера).
  • Для получения более подробной информации обратитесь к спецификации UCP .

• Ошибки/предупреждения бизнес-логики:

  • Возвращает HTTP-код 200 OK .
  • Опишите проблему в массиве messages в теле JSON-ответа.
  • Каждый объект в массиве messages должен включать в себя:
    • type : "error" или "warning"
    • code : Стандартизированный код из данного руководства. Не используйте общие или нераспознанные коды, такие как "invalid" .
    • content : описание, понятное человеку.
    • severity : Обязательно для заполнения, если type — "error" . Это поле явно указывает, является ли ошибка критической ( unrecoverable ) или позволяет предложить покупателю исправить проблему ( recoverable ), вместо того чтобы полагаться на сам код ошибки.

Типы сообщений: ошибка и предупреждение.

Поле type в массиве сообщений указывает на серьезность проблемы. UCP определяет два основных типа:

• error : указывает на то, что запрошенная операция не может быть выполнена. Платформе или пользователю, вероятно, потребуется предпринять действия и повторить попытку. См. спецификацию message-error .
  • Критический характер ошибки определяется полем severity ( unrecoverable или recoverable ), а не code ошибки.
• warning : Указывает на то, что операция не была заблокирована, но есть важная информация, которую следует сообщить пользователю. Это не останавливает процесс, но предоставляет важный контекст. См. спецификацию message-warning .

Справочник кодов ошибок

Примеры кодов ошибок

В этом разделе приведены примеры JSON-файлов для массива messages , содержащих конкретные коды ошибок.

out_of_stock

Оформление заказа на один товар:

{
  "type": "error",
  "severity": "unrecoverable",
  "code": "out_of_stock",
  "content": "Unfortunately, the item 'Example Product 1' is out of stock."
}

Оформление заказа на несколько товаров:

В поле path укажите индекс конкретного товара, которого нет в наличии.

{
  "type": "error",
  "severity": "recoverable",
  "code": "out_of_stock",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' is out of stock. Remove it from your cart to continue."
}

quantity_invalid_limit_exceeded

{
  "type": "error",
  "severity": "recoverable",
  "code": "quantity_invalid_limit_exceeded",
  "path": "$.checkout.line_items[0].quantity",
  "content": "The requested quantity for 'Example Product 2' exceeds the maximum allowed limit of 5."
}

totals_changed

{
  "type": "warning",
  "code": "totals_changed",
  "path": "$.totals[2]",
  "content": "Shipping cost has changed."
}

missing_buyer_info

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_buyer_info",
  "path": "$.buyer.first_name",
  "content": "Missing buyer first name."
}

address_undeliverable

Ограничение на уровне заказа (например, почтовый индекс не поддерживается):

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "content": "Delivery is not supported for the provided zipcode."
}

Ограничение на уровне элемента:

В поле path укажите конкретный товар, который не может быть доставлен в выбранное место назначения (например, товары, ввозимые по запретам в конкретном штате).

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' cannot be delivered to the selected address."
}

address_unverifiable

Адрес для выставления счета:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.payment.instruments[0].billing_address",
  "content": "Invalid billing address. Update the address before trying again."
}

Адрес для выполнения заказа:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.fulfillment.methods[0].destinations[0]",
  "content": "The fulfillment address couldn't be verified. Update the address and try again."
}

missing_billing_info

Используйте поле path , чтобы указать отсутствующие поля в платежном адресе.

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_billing_info",
  "path": "$.payment.instruments[0].billing_address.street_address",
  "content": "Missing billing street address."
}

identity_required

В REST API эта ошибка должна возвращаться с HTTP-статусом 401.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "identity_required",
  "content": "User identity is required to access order history."
}

insufficient_scope

В REST API эта ошибка должна возвращаться с HTTP-статусом 403.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "insufficient_scope",
  "content": "This operation requires scopes: dev.ucp.shopping.order:read, dev.ucp.shopping.order:manage"
}

payment_declined

{
  "type": "error",
  "severity": "recoverable",
  "code": "payment_declined",
  "path": "$.payment.instruments[0]",
  "content": "Payment was declined by the issuer. Try a different payment method or contact your bank."
}