Handling errors

Both the Amazon Pay widgets and the Amazon Pay API operations can throw errors. To provide the best possible buyer experience on your website, catch and handle both kinds of errors.

Handling errors from Amazon Pay API section operations

When you get an error from the Amazon Pay API section operations, you might be able to retry that operation depending on the nature of the error. Properly formed operation requests are idempotent – that is, if you call the same operation on an already successful request, you don't create a duplicate transaction.

For billing agreement requests, the idempotency key is the AmazonBillingAgreementId. For AuthorizeOnBillingAgreement, Capture, and Refund requests, the idempotency key is the AuthorizationReferenceId, CaptureReferenceId, and RefundReferenceId, respectively. For example, you cannot refund against the same capture object more than once if you provide the same RefundReferenceId. This functionality lets you safely retry any operation call if the error meets the conditions described in the table below.

If you want to retry an operation call after you receive an error, you can immediately retry after the first error response. If you want to retry multiple times, we recommend that you implement an "exponential backoff" approach up to some limit, log the error, and then proceed with a manual follow-up and investigation. For example, you can time your retries in the following time spacing: 1s, 2s, 4s, 10s, 30s. The actual backoff times and limit depend on your business processes.

The following table describes re-triable errors:

HTTP code HTTP status Description and corrective action
500 InternalServerError The server encountered an unexpected condition that prevented it from fulfilling the request. This error is safe to retry.

This error can occur if you send a request for a Sandbox session to the Production endpoints or vice versa.
502 Bad gateway A server between the client and the destination server was acting as a gateway or proxy and rejected the request. In many cases, this is an intermittent issue and is safe to retry. If the issue persists, contact your network administrator.
503 ServiceUnavailable
RequestThrottled 		There was an unexpected problem on the server side, or the server has throttled you for exceeding your transaction quota. For a complete explanation of throttling, see Throttling: Limits to how often you can submit requests in the MWS Developer Guide. The client should retry the request or reduce the frequency of requests.
504 Gateway timeout A server between the client and the destination server was acting as a gateway or proxy and timed out on the request. In many cases, this is an intermittent issue and is safe to retry.

For more information, see the Error codes section in the Amazon Pay API reference guide.

Handling errors from Amazon Pay widgets

As described in Step 1: Add a Button widget for buyer authentication, you can configure the Button, AddressBook, and Wallet widgets to notify you of error conditions. These widgets send error notifications if certain integration errors are made. The following code sample shows how you can read the errorCode and errorMessage associated with the error and show it in a text field. These error codes help you debug your integration more quickly and, if logged, can notify you of potential issues on your production site.

 
<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>

The following table lists the various error codes that are returned from the Amazon Pay widgets and the corresponding error message that the buyer sees within the widget body:

Error code Description Error message that the buyer sees
AddressNotModifiable You cannot modify the shipping address when the billing agreement is in the given state. You cannot change the shipping address for this order. Please contact the seller for assistance.
BuyerNotAssociated The buyer is not associated with the given billing agreement. The buyer must sign in before you render the widget. This session is not valid. Please restart the checkout process by clicking the Amazon Pay button.
BuyerSessionExpired The buyer's session with Amazon has expired. The buyer must sign in before you render the widget. Your session has expired. Please sign in again by clicking the Amazon Pay button.
ConfirmedBillingAgreement The specified billing agreement was already confirmed. You cannot display the consent widget for an already confirmed billing agreement. The Authorize Recurring Payments widget will not render.
CurrencyUnsupported The presentmentCurrency that is passed into the wallet widget is not supported by Amazon for your account. Amazon Pay can't be used with the selected currency (¥ CNY). Please choose a different payment option to proceed with your purchase.
InvalidAccountStatus Your merchant account is not in an appropriate state to execute this request. For example, it has been suspended or you have not completed registration. If the error happened when displaying the Button widget, the widget does not appear. No error message is shown to the buyer. If the error happened when displaying the AddressBook or Wallet widgets, the buyer sees this message:

We're sorry, but there's a problem processing your payment from this website. Please contact seller for assistance.
InvalidBillingAgreementId The specified billing agreement identifier is invalid. We're sorry, but there's a problem processing your payment from this website. Please contact the seller.
InvalidParameterValue The value assigned to the specified parameter is not valid. If the error happened when displaying the Button widget, the widget does not appear. No error message is shown to the buyer. If the error happened when displaying the AddressBook or Wallet widgets, the buyer sees this message:

We're sorry, but there's a problem processing your payment from this website. Please contact seller for assistance.
InvalidSellerId The seller identifier that you have provided is invalid. Specify a valid SellerId. If the error happened when displaying the Button widget, the widget does not appear. No error message is shown to the buyer. If the error happened when displaying the AddressBook or Wallet widgets, the buyer sees this message:

We're sorry, but there's a problem processing your payment from this website. Please contact seller for assistance.
ITP The buyer must give Amazon Pay permission to use cookies to verify their identity and securely complete transactions. Amazon Pay renders a rescue widget to get buyer permission to use cookies. When this widget is first rendered or refreshed after buyer action, the onError callback is triggered with the errorCode of ITP.

The merchant should not take action when the onError callback returns the ITP errorCode. The buyer uses the Amazon Pay rescue widget to grant permission and return to the merchant's normal checkout flow.

If the buyer chooses not to grant Amazon Pay permission to use cookies, the onError callback returns the BuyerSessionExpired errorCode.
MissingParameter The specified parameter is missing and must be provided. If the error happened when displaying the Button widget, the widget does not appear. No error message is shown to the buyer. If the error happened when displaying the AddressBook or Wallet widgets, the buyer sees this message:

We're sorry, but there's a problem processing your payment from this website. Please contact seller for assistance.
PaymentMethodNotModifiable You cannot modify the payment method when the billing agreement is in the given state. You cannot change the payment method for this order. Please contact the seller for assistance.
ReleaseEnvironmentMismatch You have tried to render a widget in a release environment that does not match the release environment of the Billing Agreement object. The release environment of the widget and the Billing Agreement object must match. We're sorry, but there's a problem processing your payment from this website. Please contact the seller for assistance.
StaleBillingAgreement The specified billing agreement was not confirmed in the allowed time and is now cancelled. You cannot associate a payment method and an address with a cancelled billing agreement. Your session has expired. Please sign in again by clicking the Amazon Pay button.
WidgetNotApplicable Your merchant account is currently not authorized for billing agreements. We're sorry, but there's a problem processing your payment from this website. Please contact the seller.
InvalidBillingAgreementStatus The specified billing agreement identifier is in an invalid state. We're sorry, but there's a problem processing your payment from this website. Please contact the seller.
AddressBookWidgetNotApplicable The Amazon AddressBook Widget cannot be rendered because the useAmazonAddressBook parameter has been set to false for the specified order reference. We're sorry, but there's a problem processing your payment from this website. Please contact seller for assistance.
BuyerNotEligible The buyer cannot use the merchant account. You cannot use the username and password associated with your merchant account. Please use a different buyer account.
UnknownError There was an unknown error in the service. We're sorry, but there's a problem processing your payment from this website. Please contact the seller.

See also

Testing your integration in the Sandbox environment