エラーハンドリング

Amazon PayのウィジェットとAmazon PayのAPI処理の両方はエラーを返します。Webサイト上で最高で実現可能な購入者エクスペリエンスを提供するためには、両者のほとんどのエラーを受け止めハンドリングしなければなりません。

Amazon Pay API処理からのエラーハンドリング

Amazon Pay API処理からのエラーを受け取った場合は、エラーの原因に応じて処理をリトライできるかもしれません。適切に構成された処理リクエストはべき等です。既に成功しているリクエストと同じ処理を呼び出した場合は、重複したトランザクションは生成されません。

Billing Agreementリクエストでのべき等のキーはAmazonBillingAgreementIdです。AuthorizeOnBillingAgreement、Capture、Refundリクエストでのべき等のキーは、それぞれAuthorizationReferenceId、CaptureReferenceId、RefundReferenceIdです。例えば、一度、同じRefundReferenceIdを提示した場合は、それ以上に同じ売上請求オブジェクトに対して返金できません。次の表で説明している条件でエラーを確認できた場合は、この機能性は、多くの処理を安全にリトライするために許可します。

エラーを受け取った後に処理をリトライしたい場合は、最初のエラーレスポンスの後に直ぐにリトライできます。複数回リトライしたい場合は、Amazonは制限に対して「指数的に減らす」アプローチを行う実装を推奨します。それから、エラーを記録し、手動でのフォローアップと調査を続行します。例えば、時間間隔を1秒、2秒、4秒、10秒、30秒としてリトライできます。実際に減らす時間と制限は、販売事業者の運用ルールによります。

次の表はエラーを説明します。

HTTP コード	HTTP ステータス	説明と調整アクション
500	InternalServerError	サーバはリクエストを実行中に予期しない状態に直面しました。このエラーはSANDBOXセッションを本番環境のエンドポイント、またはその逆にリクエストする場合に発生します。
502	Bad Gateway	クライアントと接続先サーバの間を代理しているゲートウェイやプロキシーのサーバがリクエストを拒否しました。多くのケースでは、時々途切れる問題であり、リトライしても安全です。問題が続く場合はネットワーク管理者に問合せしてください。
503	ServiceUnavailable RequestThrottled	これらはサーバサイド上の予期しない問題か、サーバはトランザクションクォーターを超えた為にスロットルされました。クライアントはリクエストをリトライするか、リクエストの回数を減らさなければなりません。
504	Gateway Timeout	クライアントと接続先サーバの間で代理しているゲートウェイやプロキシーのサーバがリクエストをタイムアウトしました。多くのケースでは、時々途切れる問題であり、リトライしても安全です。

詳しい情報は、Amazon Pay APIリファレンスガイドのエラーコードセクションを参照してください。

Amazon Payウィジェットからのエラーハンドリング

「Step1：購入者認証用のボタンウィジェット追加」で述べたように、エラー状態を通知するためのボタン、アドレス帳、お支払い方法ウィジェットを設定できます。特定のインテグレーションエラーが作成されている場合は、これらのウィジェットはエラー通知を送信します。次のサンプルコードは関連したエラーとテキストフィールドに表示するerrorCodeとerrorMessageを読むことができる方法を表します。これらのエラーコードは、本番環境上の潜在的な問題について通知を記録することで、インテグレーションのデバッグをより素早く支援します。

 
<label>Debug error code     :</label>
<div id="errorCode"></div>

<label>Debug error message  :</label>
<div id="errorMessage"></div>

<div id="addressBookWidgetDiv">
</div>

<script>
  new OffAmazonPayments.Widgets.AddressBook({
    sellerId: 'YOUR_SELLER_ID_HERE',
    onOrderReferenceCreate: function(orderReference) {
      // Here is where you can grab the Order Reference ID.
      orderReference.getAmazonOrderReferenceId();
    },
    design: {
      designMode: 'responsive'
    },
    onError: function(error) {
      document.getElementById("errorCode").innerHTML = error.getErrorCode();
      document.getElementById("errorMessage").innerHTML = error.getErrorMessage();
    }

// The following are two examples of error handling code

    onError: function(error) {
      if(error.getErrorCode() == 'ITP') {
        // take no action -- allow interaction with widgets -- remove spinner/overlay if any
        return;
      }
      if(error.getErrorCode() == 'BuyerSessionExpired') {
        // take an action to move the customer to regular checkout, perhaps reroute to cart page
        window.location.href = '//my.ecommerce-shop.com/cart'; // send to the page which has a Amazon Pay Widgets(Button)
      }
    }
  }).bind("addressBookWidgetDiv");
</script>

次の表は様々なエラーコードとして購入者がウィジェット本体内で参照するAmazon Payのウィジェットとそれに対応するエラーメッセージをリストしています。

エラーコード	説明	エラーメッセージ
AddressNotModifiable	Billing Agreementが与えられた状態では配送先住所を変更できません。	あなたはこの注文では配送先住所を変更できません。販売事業者の支援先にお問い合わせください。
BuyerNotAssociated	購入者は与えられたBilling Agreementに関連付けされていません。購入者はウィジェットが表示される前にサインインしなければなりません。	このセッションは無効です。Amazonアカウントでお支払いボタンをクリックして購入処理を再実行してください。
BuyerSessionExpired	購入者のセッションはAmazonでは期限切れです。購入者はウィジェットが表示される前にサインインしなければなりません。	セッションは期限切れです。Amazonアカウントでお支払いボタンをクリックして再度サインインしてください。
ConfirmedBillingAgreement	指定されたBilling Agreementは既に承認済です。すでに承認済のBilling Agreementの同意ウィジェットを表示することはできません。	お支払い方法設定の承認ウィジェットは表示されません。
InvalidAccountStatus	販売事業者のセラーアカウントはこのリクエストを実行するためには適切ではありません。例えば、それは停止になっているか、登録が完了しておりません。	ボタンウィジェットを表示する時にエラーが発生しウィジェットが表示されません。購入者にエラーメッセージは表示されません。アドレス帳やお支払い方法ウィジェットを表示する時にエラーが発生した場合は、購入者には次のメッセージが表示されます。申し訳ございません。このWebサイトからあなたの支払処理に問題がありました。販売事業者の支援先までお問い合わせください。
InvalidBillingAgreementId	指定されたBilling Agreement識別子は無効です。	申し訳ございません。このWebサイトからあなたの支払処理に問題がありました。販売事業者の支援先までお問い合わせください。
InvalidParameterValue	指定されたパラメータに割り与えられた値は無効です。	ボタンウィジェットを表示する時にエラーが発生しウィジェットが表示されません。購入者にエラーメッセージは表示されません。アドレス帳やお支払い方法ウィジェットを表示する時にエラーが発生した場合は、購入者には次のメッセージが表示されます。申し訳ございません。このWebサイトからあなたの支払処理に問題がありました。販売事業者の支援先までお問い合わせください。
InvalidSellerId	提示された販売事業者の識別子が無効です。正しいSellerIdを指定してください。	ボタンウィジェットを表示する時にエラーが発生しウィジェットが表示されません。購入者にエラーメッセージは表示されません。アドレス帳やお支払い方法ウィジェットを表示する時にエラーが発生した場合は、購入者には次のメッセージが表示されます。申し訳ございません。このWebサイトからあなたの支払処理に問題がありました。販売事業者の支援先までお問い合わせください。
ITP	購入者は、IDを照合して安全に取引を完了するために、クッキーの使用許可をAmazon Payに付与する必要があります。	Amazon Payは、購入者にクッキーの使用許可を得るためのレスキューウィジェットを表示します。このウィジェットが最初にレンダリングか、または購入者の操作の後に更新されると、onErrorコールバックのerrorCodeに「ITP」が発動されます。販売事業者のサイトでは、onErrorコールバックのerrorCodeとして「ITP」が返された場合は、何もアクションをしなくてもよいです。購入者はAmazon Payのレスキューウィジェットを使用して許可を付与し、販売事業者の通常のチェックアウトフローに戻ります。購入者がAmazon Payにクッキーの使用許可をしなかった場合は、onErrorコールバックはBuyerSessionExpiredエラーコードを返します。
MissingParameter	指定されたパラメータは間違いです、正しいパラメータを提供しなければなりません。	ボタンウィジェットを表示する時にエラーが発生しウィジェットが表示されません。購入者にエラーメッセージは表示されません。アドレス帳やお支払い方法ウィジェットを表示する時にエラーが発生した場合は、購入者には次のメッセージが表示されます。申し訳ございません。このWebサイトからあなたの支払処理に問題がありました。販売事業者の支援先までお問い合わせください。
PaymentMethodNotModifiable	Billing Agreementが与えられた状態では支払方法を変更できません。	この注文の支払方法は変更できません。販売事業者の支援先までお問い合わせください。
ReleaseEnvironmentMismatch	リリース環境内でのウィジェットがBilling Agreementと一致しないウィジェットの表示を試みました。リリース環境のウィジェットとBilling Agreementオブジェクトは一致しなければなりません。	申し訳ございません。このWebサイトでの支払処理に問題があります。販売事業者の支援先までお問い合わせください。
StaleBillingAgreement	指定されたBilling Agreementは許可された時間内に承認されていない為、今キャンセルされました。キャンセルされたBilling Agreementの支払方法と住所を関連付けできません。	あなたのセッションは期限切れです。Amazonアカウントでお支払いボタンをクリックして再度サインインしてください。
WidgetNotApplicable	セラーアカウントは現在Billing Agreementの認証をしておりません。	申し訳ございません。このWebサイトでの支払処理に問題があります。販売事業者にお問い合わせください。
InvalidBillingAgreementStatus	指定されたBilling Agreement識別子は無効な状態です。	申し訳ございません。このWebサイトでの支払処理に問題があります。販売事業者にお問い合わせください。
UnknownError	サービスは原因不明のエラーです。	申し訳ございません。このWebサイトでの支払処理に問題があります。販売事業者にお問い合わせください。