このページでは、ユニバーサル コマース プロトコル（UCP）を使用して Google と統合する際に API レスポンスで返す必要のある標準エラーコードの概要について説明します。一貫したエラーコードを使用することで、明確なコミュニケーションが確保され、Google がさまざまなシナリオに適切に対応できるようになります。
ビジネス エラーが発生した場合、API は、表の適切な code を含むレスポンス メッセージを返す必要があります。一部のエラーコードでは、レスポンスの messages 配列に特定の JSON 構造を使用することが推奨されています。これらの例は、テーブルの下のエラーコードの例のセクションに記載されています。これらの例では、path フィールドを使用して、リクエスト オブジェクトまたはレスポンス オブジェクト内のエラーの場所に関するより具体的な情報を提供する必要があります。
エラー処理
エラーの報告方法は、エラーの種類によって異なります。
Protocol/Server Errors:
- 形式が正しくないリクエスト、認証の失敗、サーバーの利用不可などの問題には、標準の HTTP ステータス コード（クライアント エラーの場合は 4xx、サーバー エラーの場合は 5xx など）を使用します。
- 詳しくは、UCP 仕様をご覧ください。
ビジネス ロジックのエラー/警告:
- HTTP 200 OK ステータスを返します。これには、ダウンストリームの支払いゲートウェイが 4xx または 5xx エラーを返した場合でも、支払いの拒否や不正行為の拒否が含まれます。
- JSON レスポンス本文の
messages配列内の問題を説明します。 messages配列内の各オブジェクトには、次のものを含める必要があります。type:"error"または"warning"code: このガイドの標準化されたコード。"invalid"などの一般的なコードや認識されないコードは使用しないでください。content: 人が読める形式の説明。severity:typeが"error"の場合は必須。このフィールドは、エラーが致命的（unrecoverable）かどうかを明示的に示します。また、エラーコード自体に依存するのではなく、購入者に問題を修正するよう促すことができます（recoverable）。
メッセージ タイプ: エラーと警告
メッセージ配列の type フィールドは、問題の重大度を示します。UCP では、主に次の 2 つのタイプが定義されています。
error: リクエストされたオペレーションを完了できなかったことを示します。プラットフォームまたはユーザーが対応して、もう一度試す必要がある可能性があります。message-error 仕様をご覧ください。- エラーの最終的な性質は、エラー
codeではなく、severityフィールド（unrecoverableまたはrecoverable）によって決まります。
- エラーの最終的な性質は、エラー
warning: オペレーションはブロックされなかったが、ユーザーに伝えるべき注目すべき点があることを示します。これにより、プロセスは停止しませんが、重要なコンテキストが提供されます。message-warning 仕様をご覧ください。
エラーコードの参照
| エラーコード | 推奨タイプ | 説明 |
|---|---|---|
out_of_stock |
エラー | アイテムはご利用いただけません。通常、結果は ucp.status: “error” になります。path フィールドを使用して、複数アイテムの購入手続きにおけるアイテムのインデックスを示します。以下の例をご覧ください。 |
item_unavailable |
エラー | アイテムが見つかりませんでした。通常、この場合はアイテム関連のエラーに対して ucp.status: “error” が返されます。 |
item_ineligible |
エラー | アイテムは存在するが、UCP を使用して購入できない。 |
quantity_invalid_limit_exceeded |
エラー | リクエストされた数量が許容上限を超えています。以下の例をご覧ください。 |
quantity_invalid_minimum_not_met |
エラー | リクエストされた数量が最小要件を下回っています。 |
totals_changed |
警告 | 価格またはその他の合計が前のステップから変更されています。path フィールドを使用して、どの合計が変更されたかを示します。以下の例をご覧ください。 |
totals_invalid_minimum_not_met |
エラー | 注文値が最低要件を満たしていません。 |
missing_buyer_info |
エラー | 購入者の必須情報が不足しています。path フィールドを使用して、欠落しているフィールドを指定します。以下の例をご覧ください。 |
address_undeliverable |
エラー | これは標準の UCP エラーコードです。path フィールドを使用して、特定の送信先または制限付きアイテムを示します。以下の例をご覧ください。 |
address_unverifiable |
エラー | ご提供いただいた住所を確認できませんでした。path フィールドを使用して、配送先住所か請求先住所かを示します。以下の例をご覧ください。 |
missing_fulfillment_info |
エラー | 必要な配送情報がありません。path フィールドを使用して、欠落しているフィールドを指定します。 |
eligibility_invalid |
エラー | ユーザーまたは注文がアクションの対象外です。これは標準の UCP エラーコードです。詳細については、path フィールドを使用します。 |
discount_code_invalid |
警告 | 割引コードが無効です。コードが見つからないか、形式が正しくありません。 |
discount_code_expired |
警告 | 割引コードの有効期限が切れています。 |
discount_code_already_applied |
警告 | 割引コードはすでに適用されています。 |
discount_code_combination_disallowed |
警告 | 割引コードは他の特典と併用できません。 |
discount_code_user_not_logged_in |
警告 | 割引コードを使用するには、ユーザーがログインしている必要があります。 |
discount_code_user_ineligible |
警告 | お客様は割引コードの利用対象外です。 |
missing_billing_info |
エラー | 必要なお支払い情報が不足しています。path フィールドを使用して、不足している請求先住所のフィールドを指定します。以下の例をご覧ください。 |
identity_required |
エラー | リクエストされたオペレーションにユーザー ID が必要ですが、ユーザー ID が存在しない、無効である、期限切れである、または確認できない。REST の場合は、ステータス コード 401 を使用します。以下の例をご覧ください。 |
insufficient_scope |
エラー | ユーザー ID トークンは有効ですが、オペレーションに必要なスコープがありません。REST の場合は、ステータス コード 403 を使用します。以下の例をご覧ください。 |
payment_declined |
エラー | カード発行会社または銀行によって支払いが承認されませんでした。理由としては、残高不足、不正行為の疑い、カードの問題などが考えられます。以下の例をご覧ください。 |
payment_failed |
エラー | 処理中に技術的な問題（ネットワーク エラー、ゲートウェイのタイムアウト、統合の問題など）が発生し、銀行が判断を下せなかったため、支払いが失敗しました。 |
payment_ineligible |
エラー | 選択したお支払い方法はご利用いただけません。お客様が別のお支払い方法をお試しいただく必要がある場合に適しています。 |
rejected_for_fraud |
エラー | 不正行為の疑いがあるため、注文が拒否されました。以下の例をご覧ください。 |
エラーコードの例
このセクションでは、特定のエラーコードの messages 配列の JSON の例を示します。
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."
}
rejected_for_fraud
{
"type": "error",
"severity": "recoverable",
"code": "rejected_for_fraud",
"path": "$.payment.instruments[0]",
"content": "The order was rejected due to suspected fraud. Try a different payment method."
}