Manage errors

Amazon Pay returns a reasonCode and message if there is an error with your API request. As an example, below is the response if a request is submitted with an invalid parameter value:

{
  "reasonCode": "InvalidParameterValue",
  "message": "The value provided for [Parameter] is invalid."
}

Error codes

This table describes generic error codes that Amazon Pay API endpoints can return.

HTTP status code
Reason code
Description
400 BAD_REQUEST
InvalidHeaderValue
You submitted an invalid value for at least one of the header parameters of your API call

For details, check the message element in the API response
400 BAD_REQUEST
InvalidRequest
You request is invalid

For details, check the message element in the API response
400 BAD_REQUEST
InvalidParameterValue
You submitted an invalid value for at least one of the parameters of your API call

For details, check the message element in the API response
400 BAD_REQUEST
InvalidRequestFormat
You submitted a request in invalid JSON format. Validate request body format
400 BAD_REQUEST
MissingHeaderValue
One of the header parameters is missing in the API call

For details, check the message element in the API response
400 BAD_REQUEST
MissingParameterValue
One of the mandatory request parameters is missing in the API call

For details, check the message element in the API response
400 BAD_REQUEST
UnrecognizedField
You have passed an invalid field in the request body

For details, check the message element in the API response
400 BAD_REQUEST
InvalidSandboxSimulationSpecified
You have attempted an invalid operation for the Sandbox environment

For details, check the message element in the API response
400 BAD_REQUEST
DuplicateIdempotencyKey
The IdempotencyKey that you have specified in this request was already used in a different request, and cannot be reused
400 BAD_REQUEST
InvalidParameterCombination
You attempted to use an invalid combination of parameters, check your request
400 BAD_REQUEST
CurrencyMismatch
Currency code provided in Charge does not match the currency set during checkout
400 BAD_REQUEST
InvalidAPIVersion
You have either attempted to use an unsupported API version or the API object version and API request version are incompatible
401 UNAUTHORIZED
UnauthorizedAccess
The specified merchant account is not authorized to execute this request

For example, you attempted to make a request using delegated authorization that you aren't authorized to execute
403 FORBIDDEN
InvalidAuthentication
Authentication was not successful, check the status of your credentials in Seller Central (US, EU, JP)
403 FORBIDDEN
InvalidAccountStatus
Your account or merchant's account is not in an appropriate state to execute this request

For example, your account has been suspended or you have not completed registration. Visit Seller Central (US, EU, JP) for more information
403 FORBIDDEN
InvalidRequestSignature
The signature in the Authorization header of your API call is invalid

For details, check the message element in the API response
403 FORBIDDEN
InvalidAuthorizationToken
The authorization token passed in the request is not valid
404 NOT_FOUND
ResourceNotFound
Couldn’t find requested resource
405 METHOD_NOT_ALLOWED
UnsupportedOperation
Operation not supported
405 METHOD_NOT_ALLOWED
RequestNotSupported
HTTP method not supported

For details, check the message element in the API response
408 REQUEST_TIMEOUT
RequestTimeout
The request timed out

Retry the request. However, retry does not guarantee a successful response
426 UPGRADE_REQUIRED
TLSVersionNotSupported
TLS version not supported. Upgrade to the latest SSL/TLS version
429 TOO_MANY_REQUESTS
TooManyRequests
The request is throttled, due to too many requests in a given amount of time

 You should retry the request
500 INTERNAL_SERVER_ERROR
InternalServerError
There was an unknown error in the service

Retry the request. However, retry does not guarantee a successful response
503 SERVICE_UNAVAILABLE
ServiceUnavailable
The service is currently unable to handle the request, due to a temporary overloading or maintenance

Retry the request

Retrying errors

You should immediately retry a request if you receive a response with a 429, 500, or 503 HTTP status code. 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.