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'tt 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, and then log the error and 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, please 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 discussed 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 display 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.

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 does not render.

InvalidAccountStatus

Your seller 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 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:

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:

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:

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 attempted 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 canceled. You cannot associate a payment method and an address with a canceled billing agreement.

Your session has expired. Please sign in again by clicking the Amazon Pay button.

WidgetNotApplicable

Your seller 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.