Amazon Incentives API - Errors and Mock Errors

Integration Technical Specification - Errors and Mock Errors

Endpoints of the Incentives API can produce errors organized by failure types. You can also simulate these errors using mock error codes to test your code.

Error Code Classes

We group errors into 5 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

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.

Login and Receive errors

F100 - System Errors

General errors with ErrorCode = F100, Mock Error Request ID = F1000

  • SimpleAmountIsNull
  • AmountIsNull
  • CurrencyCodeIsNull
  • GcLocked
  • EmptyCardInfoList
  • RequestError

F200 - Partner Input Errors

For all partner input errors, ErrorCode = F200.

Error Message and 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
RequestedDenominationMismatch ErrorType – PreDenominationMismatch
Pre Denomination Mismatch – The Card was created with a different denomination
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
ActivationNotAllowed ErrorType – InvalidCardStatusForActivation
Current card status is not valid for activation
Mock: F2011
DeactivationNotAllowed ErrorType – InvalidCardStatusForDeactivation
Current card status is not valid for deactivation
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 ErrorType – GeneralError
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 ErrorType – InvalidCardNumber
Invalid Card Number
Mock: F2023
CardNumberCheckSumError ErrorType – InvalidCardNumber
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

For all partner account, access, and onboarding errors, ErrorCode = F300.

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

All other endpoint errors

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

Mock error codes

You can simulate error conditions to fully test your code paths. The following table shows mock codes that can be passed to an operation to simulate certain error conditions. To simulate an error condition, pass the mock code in the *requestId field of the operation request.

Note: Not all operations support all mock codes.

Mock code and error name Remarks
F2000 - InvalidRequestInput  
F2001 - InvalidCardNumberInput  
F2002 - InvalidPartnerIdInput  
F2003 - InvalidAmountInput  
F2004 - InvalidAmountValue Amount must be greater than 0
F2005 - InvalidCurrencyCodeInput  
F2006 - InvalidRequestIdInput  
F2007 - CardNotFound  
F2008 - RequestedDenominationMismatch  
F2009 - CardActivatedWithDifferentDenomination  
F2010 - CardActivatedWithDifferentRequestId  
F2011 - ActivationNotAllowed  
F2012 - DeactivationNotAllowed  
F2013 - ActivationRequestIdAlreadyBeenUsed  
F2014 - NegativeOrZeroAmount  
F2015 - MaxAmountExceeded Amount greater than maximum value allowed in the national market segment (e.g. $500 in US)
F2016 - CurrencyCodeMismatch  
F2017 - FractionalAmountNotAllowed Fractional amount not allowed in this currency (e.g. JP)
F2018 - NonExistingActivationRequestId  
F2019 - WrongActivationRequestId  
F2020 - GcNotReadyForRefund  
F2021 - RequestIdTooLong RequestId greater than 40 characters
F2022 - RequestIdMustStartWithPartnerName  
F2023 - CardNumberTooShort  
F2024 - InvalidGCIdInput  
F2025 - InvalidRequest  
F2026 - MaxPageSizeExceeded  
F2027 - InvalidPageSize  
F2028 - InvalidPageIndex  
F2029 - InvalidStartDate  
F2030 - InvalidEndDate  
F2031 - StartDateAfterEndDate  
F2032 - InvalidDateFormat  
F2033 - InvalidAccountType Account type provided in request is undefined
F2034 - UndefinedAccountId AccountId provided in request does not exist in Amazon system
F2035 - AccountIdNotInValidStatus AccountId not in valid status for requested operation (e.g. AccountId is deactivated)
F2036 - InvalidCurrencyInMarketplace  
F2037 - AmountBelowMinThreshold  
F2038 - LoadBalanceRequestIdAlreadyUsed loadBalanceRequestId provided in load API has already been used (e.g. when idempotenccy check of the given loadBalanceRequestId fails)
F2039 - LoadBalanceRequestIdDoesNotExist  
F2040 - RequestMismatchFromLoadRequest Parameters passed in a void request do not match the parameters of a Load request
F2041 - BalanceLoadCannotBeVoided When the loaded balance has been used and voidIfUsed flag is false
F2042 - ExternalReferenceTooLong  
F2043 - NotificationMessageTooLong The value used in the notificationDetails parameter exceeds 250 Unicode characters
F2044 - SourceIdTooLong The value used in the sourceID field exceeded the max number of 40 Unicode characters
F2045 - BalanceLoadCannotBeVoidedDueToTimeout  
F2046 - InvalidPhoneNumber  
F2047 - CancelRequestArrivedAfterTimeLimit  
F2048 - ProgramIdNotPresent  
F3000 - UnknownCustomer  
F3001 - InvalidAwsAccessKeyId  
F3002 - BlockedCustomer  
F3003 - 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 you make a payment)
F3004 - IssuanceCapExceeded The balance issuance limit defined by the contract has been reached for the specified time period
F3005 - AccountHasProblems  
F3006 - 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)
F3007 - BadInput  
F3008 - APIGetGiftCardActivityPageIsDisabled  
F3009 - ActiveContractNotFound Your account set up is not complete
F3010 - CustomerSurpassedDailyVelocityLimit  
F3011 - CustomerAccountBlocked This Amazon account is not allowed to perform this transaction
F3012 - ProductTypeNotEnabledInTheContract  
F3013 - InvalidProgramId  
F3014 - ProgramIsNotApproved  
F4000 - SystemTemporarilyUnavailable Amazon system is temporarily not available. Note: Response Status would be “RESEND” and not Failure. See Error Handling
F5000 - UnknownError  

Testing scenarios using mock codes

API success and error responses can be tested by sending mock requests. Success response can be mocked by using mock code F0000. Error responses can be mocked by using mock error codes provided in error codes table.

A mock request uses account type 0 and account Id is a mock (error) code. For example, to send a mock request for success response on LoadAmazonBalance API, use account Id F0000.

Example Mocking Request

<LoadAmazonBalanceRequest>
    <account>
        <id>F0000</id>
        <type>0</type>
    </account>
    <partnerId>PartnerUS</partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>A1234</institutionId>
        <sourceDetails>{"institutionName": "Test Merchant"}</sourceDetails>
    </transactionSource>
</LoadAmazonBalanceRequest>

Example Mocking Response

<LoadAmazonBalanceResponse>
    <account>
        <id>F0000</id>
        <type>0</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</LoadAmazonBalanceResponse>

Mocking error:

Following request mocks UndefinedAccountId error:

Mocking Request

<LoadAmazonBalanceRequest>
    <account>
        <id>F2034</id>
        <type>0</type>
    </account>
    <partnerId>PartnerUS</partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>A1234</institutionId>
        <sourceDetails>{"institutionName": "Test Merchant"}</sourceDetails>
    </transactionSource>
</LoadAmazonBalanceRequest>

Error Response

<LoadAmazonBalanceException>
    <errorCode>F200</errorCode>
    <errorType>UndefinedAccountId</errorType>
    <errorMessage>AccountId provided in request does not exist in Amazon system</errorMessage>
    <status>FAILURE</status>
</LoadAmazonBalanceException>

Mocking Test Examples

Successful mocking test with requestId=F0000

PAYLOAD

<CreateGiftCardRequest>
    <creationRequestId>F0000</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>phonybucks</currencyCode>
        <amount>-3.14159</amount>
    </value>
</CreateGiftCardRequest>

HASHED PAYLOAD

7ea6c536e7586fb525f49aaeb4fd3c6971a696f125da6447d12d29a1973fb004

CANONICAL REQUEST

POST
/CreateGiftCard
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T170041Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
accept;content-type;host;x-amz-date;x-amz-target
7ea6c536e7586fb525f49aaeb4fd3c6971a696f125da6447d12d29a1973fb004

HASHED CANONICAL REQUEST

0d1c6d7d24f929697e7eae8edae3405d8185c93ccbef2ca5bd098eaa10be42fb

STRING TO SIGN

AWS4-HMAC-SHA256
20140205T170041Z
20140205/us-east-1/AGCODService/aws4_request
0d1c6d7d24f929697e7eae8edae3405d8185c93ccbef2ca5bd098eaa10be42fb

DERIVED SIGNING KEY

07ef165a0531f64ac7ba835805728d63c296be4d0012a226454795f74644aa02

SIGNATURE

bf772d6fd53ae30f0439e6362e7a9b9dd570893d5db66950d6bbcb72a0a08da3

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CreateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T170041Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140205/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=bf772d6fd53ae30f0439e6362e7a9b9dd570893d5db66950d6bbcb72a0a08da3
<CreateGiftCardRequest>
    <creationRequestId>F0000</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>phonybucks</currencyCode>
        <amount>-3.14159</amount>
    </value>
</CreateGiftCardRequest>

Failure mocking test with requestId “F2005”

PAYLOAD

<CreateGiftCardRequest>
    <creationRequestId>F2005</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>-3.14159</amount>
    </value>
</CreateGiftCardRequest>

HASHED PAYLOAD

a425f0a78f494a56033e3ddf07c592bd97060eed8d337d30ed3965ddce235699

CANONICAL REQUEST

POST
/CreateGiftCard

accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T170938Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
a425f0a78f494a56033e3ddf07c592bd97060eed8d337d30ed3965ddce235699

HASHED CANONICAL REQUEST

3c313ac758bd441cfae841705c1449ef3c47267c355a547665d6c3afe05e4cd3

STRING TO SIGN

AWS4-HMAC-SHA256
20140205T170938Z
20140205/us-east-1/AGCODService/aws4_request
3c313ac758bd441cfae841705c1449ef3c47267c355a547665d6c3afe05e4cd3

DERIVED SIGNING KEY

07ef165a0531f64ac7ba835805728d63c296be4d0012a226454795f74644aa02

SIGNATURE

f00fea4fa7812f7910c90e6ffb9e973c45b80ce9f1e05228a1fdde1d87cde075

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CreateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T170938Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140205/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=f00fea4fa7812f7910c90e6ffb9e973c45b80ce9f1e05228a1fdde1d87cde075
<CreateGiftCardRequest>
    <creationRequestId>F2005</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>-3.14159</amount>
    </value>
</CreateGiftCardRequest>

RESPONSE

<AGCODValidationException>
  <Message>Currency Code can't be null or empty</Message>
  <errorType>InvalidCurrencyCodeInput</errorType>
  <errorCode>F200</errorCode>
  <agcodResponse>
    <status>FAILURE</status>
  </agcodResponse>
</AGCODValidationException>

F500 – Unknown Error

UnknownError
ErrorCode – F500
ErrorType – GeneralError
Message – GeneralError
Mock Error Request ID – F5000

An F500 error can occur for many reasons. This error will occur when a 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. If possible, include this information in your communication:

  • Your Partner ID
  • Complete Request/Response pair of your call to the AGCOD Gateway
  • Complete endpoint URL used (including the Server URL) to make the request
  • The StringToSign used in the request, if not already in the Request/Response above
  • The corresponding signature of the StringToSign used, if not already in the Request/Response above
  • Approximate time (with time zone) of your request (the time zone that is configured on the machine issuing the above request)
  • Programming language used
  • Any recent changes (both programming and infrastructure) on your end
  • Screenshot of error
  • Your technical contact email/phone #
  • Your time zone

Last updated: Oct 30, 2020