Handling errors from Amazon Pay API calls
When you get an error from an Amazon Pay API call, you might be able to retry that operation, depending on the nature of the error. For a list of errors that you can retry, see the table below. If you make an API call with a unique reference ID, you can call the same operation on an already successful request, and it will not create a duplicate transaction. Instead of initiating a new request, the call will return the result of the initial call.
For order reference requests, the unique (idempotency) reference ID is the AmazonOrderReferenceId. For authorise, capture, and refund requests, the unique ID is the AuthorizationReferenceId, CaptureReferenceId, and RefundReferenceId, respectively.
For example, you can't 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 a defined 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, and 30s. The actual backoff times and limit will depend on your business processes.
The following table describes errors that you can retry:
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 end points 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.