エラーコード

このページでは、ユニバーサル コマース プロトコル（UCP）を使用して Google と統合する際に API レスポンスで返す必要のある標準エラーコードの概要について説明します。一貫したエラーコードを使用することで、明確なコミュニケーションが確保され、Google がさまざまなシナリオに適切に対応できるようになります。

ビジネス エラーが発生した場合、API は、表の適切な code を含むレスポンス メッセージを返す必要があります。一部のエラーコードでは、レスポンスの messages 配列に特定の JSON 構造を使用することが推奨されています。これらの例は、テーブルの下のエラーコードの例のセクションに記載されています。これらの例では、path フィールドを使用して、リクエスト オブジェクトまたはレスポンス オブジェクト内のエラーの場所に関するより具体的な情報を提供する必要があります。

重要: 公開されている正規コードを厳守し、invalid などの一般的なコードは使用しないでください。認識されないエラーコードを返すと、Google の UI が一般的な「エラーが発生しました」というメッセージにフォールバックし、購入手続きのユーザー エクスペリエンスが低下します。

エラー処理

エラーの報告方法は、エラーの種類によって異なります。

• 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"
}

お支払いに関するエラー

注: REST API では、支払い関連のエラーは HTTP ステータス コード 200 OK で返す必要があります（4xx または 5xx エラーではありません）。これにより、Google はこれらを回復可能なビジネスエラーとして扱い、ユーザーが別のお支払い方法を選択できるようになります。

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."
}