Errors and Mock Errors
Endpoints of the Incentives API can produce errors organized by failure types.
Note: Want to test your systems response to our error codes?
Send a request to our API with the Mock Error Code as the
requestID/accountID.
See the Mock Error Code section for more informationError 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 |
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 detailsYour access key and secret key don't match. |
| F300 | Insufficient FundsYou do not have enough credits or funds to create, activate, or load balance into a gift card. |
| F300 | ActiveContractNotFoundYou do not have a valid contract to create, activate, or load balance. |
| F400 | SystemTemporarilyUnavailableThis 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.
Amazon Gift Card On Demand Errors
See the below sections that cover the error type categories
Note: Need to mock a
SUCCESS? You can do that by setting the Mock Error Code as F0000F100 - 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 |
Physical 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 |
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 |
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 |
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.
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.
Note: Not all operations support all mock codes.
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>
Next
- Check out our FAQ Page
Last updated: Oct 01, 2021