Errors and Mock Errors

Endpoints of the Incentives API can produce errors organized by failure types.

Error Code Classes

We group errors into 6 categories.

Error Code Description
F100 Amazon Internal Error
F200 Invalid Request Error (something is incorrect in the request payload)
F300 Account related Error (typically due to onboarding, authentication, access related issues, etc.)
F400 Retry able Error (Temporary issue). See Error Handling
F500 Unknown Error
Throttled You have exceeded the allowed TPS rate for your integration

↑ Back to top

Most common error codes and causes

Common Error Code Typical Cause
F200 The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key and signing method. Consult the service documentation for details
Your access key and secret key don't match.
F300 Insufficient Funds
You do not have enough credits or funds to create, activate, or load balance into a gift card.
F300 ActiveContractNotFound
You do not have a valid contract to create, activate, or load balance.
F400 SystemTemporarilyUnavailable
This is a retry-able error. You can Cancel / Deactivate / Void your original request ID, and re-send Create / Activate / BalanceLoad API.

Your system will need have built in mechanism to react to these error codes. See our Test Cases page on how you should react to each of these errors.

↑ Back to top

Amazon Gift Card On Demand Errors

See the below sections that cover the error type categories

F100 - System Errors

General errors are covered with only one Mock Error RequestID = F1000

Mock Error Request ID = F1000
SimpleAmountIsNull
AmountIsNull
CurrencyCodeIsNull
GcLocked
EmptyCardInfoList
RequestError

F200 - Partner Input Errors

Error Message Mock Error ID
InvalidRequestInput Request body is null Mock: F2000
InvalidCardNumberInput Card number can't be null or empty Mock: F2001
InvalidPartnerIdInput Partner Id can't be null or empty Mock: F2002
InvalidAmountInput Amount can't be null Mock: F2003
InvalidAmountValue Amount must be larger than 0 Mock: F2004
InvalidCurrencyCodeInput Currency Code can't be null or empty Mock: F2005
InvalidRequestIdInput Request Id can’t be null or empty Mock: F2006
CardNumberNotFound Card Number Not Found Mock: F2007
PreDenominationMismatch PPhysical card is trying to be activated for a different amount than the assigned value OR digital card created for one amount, then being called to create again for another amount (without canceling the card first). Please match the assigned value of the gift card for activate or create calls. Mock: F2008
CardActivatedWithDifferentDenomination The card was already activated with a different denomination Mock: F2009
CardActivatedWithDifferentRequestId The card was already activated with a different request id Mock: F2010
InvalidCardStatusForActivation Current card status is not valid for activation. It could be already activated or claimed or been invalidated by Amazon. Mock: F2011
InvalidCardStatusForDeactivation Current card status is not valid for deactivation. It is already deactivated or claimed or been invalidated by Amazon. Mock: F2012
ActivationRequestIdAlreadyBeenUsed Activation RequestId Already Been Used Mock: F2013
NegativeOrZeroAmount Negative Or Zero Amount Mock: F2014
MaxAmountExceeded Max Amount Exceeded Mock: F2015
CurrencyCodeMismatch Currency Code Mismatch Mock: F2016
FractionalAmountNotAllowed Fractional Amount Not Allowed Mock: F2017
NonExistingActivationRequestId No matching activation request ID Mock: F2018
WrongActivationRequestId Wrong Activation RequestId Mock: F2019
GcRTPNotAllowed General Error Mock: F2020
RequestIdTooLong Request Id Too Long, Max allowed length is 40 Mock: F2021
RequestIdMustStartWithPartnerName Request Id Must Start With Partner Name Mock: F2022
CardNumberTooShort Invalid Card Number Mock: F2023
CardNumberCheckSumError Invalid Card Number Mock: F2023
InvalidGCIdInput GC Id can't be null or empty Mock: F2024
InvalidRequest GC Id can't be null or empty Mock: F2025
MaxPageSizeExceeded Max Page Size Exceeded Mock: F2026
InvalidPageSize Invalid Page Size Mock: F2027
InvalidPageIndex Invalid Page Index Mock: F2028
InvalidStartDate Invalid Start Date Mock: F2029
InvalidEndDate Invalid End Date Mock: F2030
StartDateAfterEndDate Start Date After End Date Mock: F2031
InvalidDateFormat Invalid Date Format Mock: F2032
ExternalReferenceTooLong External Reference is too long Mock: F2042
CancelRequestArrivedAfterTimeLimit Cancellation cannot be processed as too much time has elapsed since creation Mock: F2047
ProgramIdNotPresent Program Id is not present Mock: F2048

↑ Back to top

F300 - Partner Account/Access/Onboarding Errors

Error Message Mock Error ID
InvalidPartnerId Invalid Partner Id Mock: F3000
InvalidAccessKey Invalid Access Key Mock: F3001
AccessDenied Access Denied Mock: F3002
InsufficientFunds Insufficient Funds Mock: F3003
GeneralError General Error Mock: F3005
AccountHasProblems General Error Mock: F3005
OrderNotFound General Error Mock: F3005
WrongGcOrderSource General Error Mock: F3005
WrongGcOrderType General Error Mock: F3005
GcOrderBelongToOtherCustomer General Error Mock: F3005
OperationNotPermitted Operation Not Permitted Mock: F3006
BadInput Bad Input Data Mock: F3007
APIGetGiftCardActivityPageIsDisabled GeneralError Mock: F3008
ActiveContractNotFound Active Contract Not Found Mock: F3009
InvalidProgramId Program Id does not exist in Amazon system Mock: F3010
ProgramIsNotApproved Program is not approved Mock: F3011

↑ Back to top

Other Endpoint Errors

Error Type Description Error Code / Mock
GeneralError Amazon internal error F100 / F1000
BalanceLoadCannotBeVoided Unable to void balance load due to Amazon internal error F100 / F1001
InvalidRequestInput The request body is null F200 / F2000
InvalidPartnerIdInput partnerId cannot be null F200 / F2002
InvalidAmountInput Amount cannot be null F200 / F2003
InvalidAmountValue Amount must be greater than 0 F200 / F2004
InvalidCurrencyCodeInput Currency code cannot be null F200 / F2005
InvalidRequestIdInput loadBalanceRequestId cannot be null F200 / F2006
MaxAmountExceeded Amount greater than maximum value allowed in the national market segment (e.g. $500 in US) F200 / F2015
FractionalAmountNotAllowed Fractional amount not allowed in the currency (e.g. JP) F200 / F2017
RequestIdTooLong loadBalanceRequestId greater than 40 characters F200 / F2021
RequestIdMustStartWithPartnerName loadBalanceRequestId must begin with partnerId F200 / F2022
InvalidAccountType Account type provided in request is undefined F200 / F2033
UndefinedAccountId AccountId provided in request does not exist in Amazon system F200 / F2034
AccountIdNotInValidStatus AccountId not in valid status for requested operation (e.g. AccountId is deactivated) F200 / F2035
InvalidCurrencyInMarketplace Currency code is not supported in national market segment where AccountId is created F200 / F2036
AmountBelowMinThreshold Amount below minimum required amount F200 / F2037
LoadBalanceRequestIdAlreadyUsed loadBalanceRequestId provided in load API has already been used (e.g. when idempotency check of the given loadBalanceRequestId fails) F200 / F2038
LoadBalanceRequestIdDoesNotExist Load request with loadBalanceRequestId provided in the void API does not exist F200 / F2039
RequestMismatchFromLoadRequest Parameters passed in a void request do not match the parameters of a Load request F200 / F2040
BalanceLoadCannotBeVoided When the loaded balance has been used and voidIfUsed flag is false F200 / F2041
ExternalReferenceTooLong The value used exceeds the max number of Unicode characters F200 / F2042
NotificationMessageTooLong The value used in the notificationDetails parameter exceeds 250 Unicode characters F200 / F2043
SourceIdTooLong The value used in the sourceID field exceeded the max number of 40 Unicode characters F200 / F2044
BalanceLoadCannotBeVoided Unable to void balance, request arrived beyond the time limit F200 / F2045
InvalidPartnerId partnerId used in API request does not exist in Amazon system F300 / F3000
InvalidAccessKey Security access key used to sign the request does not exist in Amazon system (not applicable in China) F300 / F3001
InvalidAccessKey Access key (in China) used to sign API request does not exist in Amazon system F300 / F3001
AccessDenied The account is blocked F300 / F3002
InsufficientFunds The account does not have sufficient funds to issue the request amount (each partner is given certain credit limit and the partner can issue balance only up to the credit limit. Credit limit is reset when the partner makes a payment) F300 / F3003
IssuanceCapExceeded The balance issuance limit defined by the contract has been reached for the specified time period F300 / F3004
OperationNotPermitted The request is denied. Partner does not have permission to call the API (happens when non Amazon Balance Load distribution partner tries to call an Amazon Balance Load API before onboarding) F300 / F3006
ActiveContractNotFound Partner account set up is not complete F300 / F3009
CustomerSurpassedDailyVelocityLimit Customer has exceeded daily velocity limit F300 / F3010
CustomerAccountBlocked This Amazon account is not allowed to perform this transaction F300 / F3011
SystemTemporarilyUnavailable Amazon system is temporarily not available. Note: Response Status would be RESEND and not Failure. See Error Handling F400 / F4000
GeneralError Unknown error F500 / F5000

↑ Back to top

F500 – Unknown Error

Unknown Errors are covered in with the Mock Error Request ID - F5000

An F500 error can occur for many reasons and can be used where no other error code covers the scenario. An F500 can also be passed where there is a system outage.

Example

An F500 will be returned request body in JSON format fails to use camelCase for element names.

Examples of camelCase: creationRequestId, partnerId, value, amount, and currencyCode.

For any other F500 error, contact Amazon. You can find more information on our outage page.

↑ Back to top

Throttled

Throttling Exception will occur when you have exceeded the allowed TPS rate for your integration or operation method. You should slow your system down or implement a throttling mechanic that ensures you don't breach your TPS limit.

You should also not instantly retry a throttled request as this will case an infinite loop which will require Amazon to temporarily disable your integration.

Throttled messages look like the below

<ThrottlingException>
    <Message>Rate exceeded</Message>
</ThrottlingException>

Mock error codes

You can simulate error conditions to fully test your code paths.

API success and error responses can be tested by sending mock requests. Success response can be mocked by using mock code F0000. Error Codes can be mocked by using the Mock Error codes shared in the above tables.

Error Testing Request & Responses

For CreateGiftCard and ActivateGiftCard calls, when testing Mock Error Codes, you must replace the requestID with the Mock Error Code you are attempting to simulate.

For LoadAmazonBalance the Mock Error Code replaces the accountID. The accountType must be set as 0.

Example Mock Requests

CreateGiftCard
<CreateGiftCardRequest>
	<creationRequestId>F2012</creationRequestId>
	<partnerId>Awssb</partnerId>
	<value>
		<currencyCode>EUR</currencyCode>
		<amount>1.00</amount>
	</value>
</CreateGiftCardRequest>
ActivateGiftCard
<ActivateGiftCardRequest>
	<activationRequestId>F2005</activationRequestId>
	<partnerId>Awssb</partnerId>
	<cardNumber>3400000000004400616</cardNumber>
	<value>
		<currencyCode>EUR</currencyCode>
		<amount>1</amount>
	</value>
	<transactionSource>
		<id>{"institutionId" : "1010101010" , "sourceId" : "01010101010101"}</id>
	</transactionSource>
</ActivateGiftCardRequest>
LoadAmazonBalance
<LoadAmazonBalanceRequest>
	<account>
		<id>F2034</id>
		<type>0</type>
	</account>
	<partnerId>Awssb</partnerId>
	<amount>
		<currencyCode>EUR</currencyCode>
		<value>4570</value>
	</amount>
	<loadBalanceRequestId>Awssb000000001</loadBalanceRequestId>
	<timestamp>1464933146000</timestamp>
	<transactionSource>
		<sourceId>12344332</sourceId>
		<institutionId>A1234</institutionId>
		<sourceDetails>{"institutionName": "Test Merchant"}</sourceDetails>
	</transactionSource>
</LoadAmazonBalanceRequest>

Example Error Responses

CreateGiftCard
<AGCODException>
	<agcodResponse>
		<status>FAILURE</status>
	</agcodResponse>
	<errorType>InvalidCardStatusForDeactivation</errorType>
	<errorCode>F200</errorCode>
	<Message>Current card status is not valid for deactivation</Message>
</AGCODException>
ActivateGiftCard
<AGCODValidationException>
	<errorType>InvalidCurrencyCodeInput</errorType>
	<agcodResponse>
		<status>FAILURE</status>
	</agcodResponse>
	<errorCode>F200</errorCode>
	<Message>Currency Code can't be null or empty</Message>
</AGCODValidationException>
LoadAmazonBalance
<LoadAmazonBalanceException>
	<errorCode>F200</errorCode>
	<errorType>UndefinedAccountId</errorType>
	<errorMessage>AccountId provided in request does not exist in Amazon system</errorMessage>
	<status>FAILURE</status>
</LoadAmazonBalanceException>

↑ Back to top


Next


Last updated: Oct 01, 2021