NOTE: All Aeropay errors return with HTTP 200 response

Error responses include a 'success' value of false, along with a 'code' value, i.e. (AP002), and a message 'error' that contains more information on the issue

{
    "success": false,
    "code": "AP700",
    "error": "Missing required Parameter: 'merchantId'"
}

POST /token and some newer endpoints return error codes and messages nested in 'error' exampled below

{
    "success": false,
    "error": {
        "code": "AP002",
        "message": "invalid API key or secret key"
    }
}

Aeropay Error Glossary

Authentication & General Errors (AP00X)

Error Code	Meaning	Resolution	Message
AP001	Invalid API Keys or API keys were not provided.	Double check API Key/secret and other params	"API key and secret key required"
AP002	API key/secret invalid or insufficient permissions on merchant/user	Double check API Key/secret and other params	"Invalid API key or secret key"
AP003	Your merchant account is locked.	Please reach out to the Aeropay team.	"Account locked"
AP004	Missing token.	Include the authorization token in your header of your request.	"Missing authorization header token"
AP005	Client session is invalid.	Refresh your session.	"Session does not match client."
AP006	Unauthorized user	Check the token of your call to ensure you're using the correct scope.	"Client is not authorized for this scope."
AP007	Token has expired.	Retrieve a new token.	"Token has expired"
AP008	Invalid token.	Retrieve a new token.	"Invalid token"
AP009	MerchantUser not authorized for merchantId.	Check the API URL and token to ensure you're in the correct scope.	"Unauthorized"
AP010	MerchantUser not authorized for call.	Check the API URL and token to ensure you're in the correct scope.	"Unauthorized"
AP011	MerchantUser not authorized for transaction.	Check the API URL and token to ensure you're in the correct scope.	"Unauthorized"

Users & Merchants (AP1XX & AP2XX)

Error Core	Meaning	Resolution	Message
AP101	Invalid or missing authentication token	Double check correct token and token scope is being used, and that 'authenticationToken' is provided in headers of call	"No Authenticated User"
AP102	Error creating user in the database	Check that the user information is correct, or retry at a later date.	"Unable to create user."
AP103	Issue with user reputation	There is an issue setting the user's reputation. Reach out to Aeropay support.	"Unable to set user reputation level for user {user}"
AP104	User information not provided during user creation	Ensure all necessary information is provided on user profile.	"Can not extract user information."
AP105	Area code missing	Provide area code for phone number	"Phone number {phone_number} missing area code."
AP106	Improper phone number format	Ensure phone number is properly formatted	"Phone number {phone_number} is improperly formatted."
AP107	User already exists	User already exists for the provided account information. You may need to verify the user or fetch their information.	"User already exists"
AP108	Cannot create user	Error creating a new user. Reach out to Aeropay support.	"Error adding user"
AP109	User is disabled	The user should email [email protected] if they’ve made payments. If they are a new user, they should contact [email protected]	"We've detected delinquent activity on your account. Reach out to [email protected] to reactivate your account."
AP110	User is missing required info to transact	Verify user has valid first and last names, email and phone number	"Your profile is incomplete. Please contact [email protected] to finish setting up before completing this transaction."
AP111	Invalid MFA code	Provided user verification code is incorrect, prompt user to enter correct code.	"Invalid verification code"
AP112	Failed MFA too many times	Failed user verification too many times. User will have to retry later.	"Max attempts exceeded"
AP113	User does not exist	This user does not exist. Ensure you have the correct userId.	"User does not exist"
AP115	Phone number invalid	Ensure the phone number being used is a valid US mobile number in ISO format (+1XXXXXXXXXX). Landlines, VOIPs, or prepaid numbers are invalid.	"We're sorry, but the type of phone you entered is not supported or invalid. Please enter a valid mobile number to proceed."
AP201	Unable to fetch merchant	This merchant does not exist. Ensure you have the correct merchantId.	"No merchant exists for username {merchant_id}"
AP202	Unable to fetch merchant	This merchant does not exist. Ensure you have the correct merchantId.	"No merchant user exists for merchant user id {user_id}."
AP203	Unable to fetch location	This locationid may not exist. Ensure you have the correct locationid.	"Unable to get location for merchant id {merchant_id}."
AP204	Location not for merchant	This locationid does not exist for your merchant. Ensure you have the correct locationid.	"Location {location} not for merchant."
AP205	Unable to get rewards and fees	Failed to get rewards and fees. Reach out to Aeropay	"Unable to get rewards and fees for merchant {merchant}."
AP206	Unable to get merchant	Failed to get merchant. Reach out to Aeropay.	"Unable to get merchant account for id {account_id}."
AP207	Unable to find merchant	Unable to find a merchant by id. Ensure you have the correct merchantId.	"No Merchant found for id {merchant}."
AP208	Unable to find merchant by uuid	Unable to find merchant by uuid. Ensure you have the correct location uuid.	"Failed to fetch location for uuid {uuid}."
AP209	Location and merchant do not match	Location uuid and merchantId do not match. Ensure you have the correct merchantId and location uuid.	"Location uuid {uuid} does not match the merchant {merchant}."
AP210	Merchant not verified	Your merchant account is not verified. Contact Aeropay compliance for more details.	"This merchant is not activated, please contact [email protected] for more information."

Transactions (AP3XX)

Error Code	Meaning	Resolution	Message
AP300	Bank Connection Error	The balance refresh of this user’s account failed and is usually caused by the user resetting their banking password or security settings within online banking. Balances will also become stale within 6-12 months. This is called a UAR (User-Action Required) error where the user must reconnect their account or contact Aeropay where we will assess if we can override their balance check.	"We are having issues connecting to your bank. Try reconnecting your bank or reach out to [email protected] to resolve the issue."
AP301	Blocked User	This user's account is currently in a blocked status. Direct the user to contact [email protected] to resolve the issue.	"User {username} is blocked."
AP302	Insufficient Funds	The user’s current balance does not meet the transaction amount. Pending transactions in the user’s account may be impacting the total available balance. The user must deposit additional funds into their connected account. (This may take 1-2 business days to be reflected)	"We could not approve your payment. Your available balance might be insufficient for this transaction. Please add more funds to your account or contact [email protected] for more information."
AP303	Transaction Missing Location	The transaction request is missing the location code required to complete the payment. Please reach out to Aeropay for assistance.	"Transaction missing location."
AP304	Amount exceeds maximum limit for merchant	The requested transaction amount exceeds the daily limit on your merchant account. Please reach out to Aeropay for assistance.	"'Transaction amount {amount} exceeds limit.'"
AP305	Account Blocked	Specific to /payoutTransaction: The user has an outstanding declined transaction. The user should email [email protected] if they’ve made payments. If they are a new user, they should contact [email protected]	"We've detected delinquent activity on your account. Reach out to [email protected] to reactivate your account."
AP306	Balance does not meet requirement	The user's available bank account balance is insufficient to cover the transaction. The user must deposit additional funds into their connected account. (This may take 1-2 business days to be reflected)	"We could not approve your payment. Your available balance might be insufficient for this transaction. Please add more funds to your bank account or contact [email protected] for more information".
AP307	Transaction Not Approved	Aeropay’s machine learning model did not approve the transaction after assessing its likelihood to decline. The user may contact the Aeropay Team for a possible override at [email protected]	"We could not approve your payment. Our AI protection engine predicts this transfer could overdraft. Try a smaller amount or contact [email protected]. FAQ."
AP308	Invalid amount	The amount submitted for the transaction does not match a standard monetary format. Please retry the amount with a limit of two decimal places.	"'Invalid amount: {reason}'"
AP310	Credit transaction was declined	The transaction request was malformed. Please reach out to Aeropay for assistance.	"We're sorry, your transaction request has been declined."
AP311	Bank Account attempted to be removed while it still has pending payments	A user's active bank account cannot be removed until pending payments are resolved. Please wait until the user's pending payments are completed before removing the account or contact Aeropay for more information.	"Bank Account has pending payments."
AP312	Preauth already captured	Specific to /preauthTransaction: this preauthorized transaction has already been captured.	"Preauth has already been captured by Transaction #{transaction}."
AP313	Preauth capture ineligible	The preauth transaction is not eligible for capture. Please contact Aeropay for more information. This error is common when trying to capture canceled preauth transactions.	"Preauthorized Transaction with status of {status} not eligible for capture."
AP314	Transaction uuid already exists	The transaction UUID is already in use. Please provide unique transaction uuids that follow standard UUID formating.	"Transaction with uuid of {uuid} already exists"
AP315	Guardrail reject	This transaction was rejected by Aeropay's guardrails. Please contact Aeropay for more information.	"We could not approve your payment. Our AI protection engine predicts this transfer could overdraft. Try a smaller amount or contact [email protected] "

Bank Linking (AP4XX & AP5XX)

Error Code	Meaning	Resolution	Message
AP400	User has no banks connected and cannot transact	Connect a bank account for user	"Connect your bank account to initiate a transaction."
AP401	Bank account id does not belong to user attempting to transact	Provide valid bankAccountId or remove bankAccountId param and transaction will use user's default bank account	"We cannot validate the account you're attempting to connect. Please connect a valid account."
AP402	Merchant bank account invalid	Your merchant account may not have a valid bank account. Reach out to your Aeropay representative.	"No bank account for merchant id {merchant}."
AP403	Blocked routing number	The users's bank account has been disabled for security purposes. Try again later.	"Sorry, your bank is not supported at this time. Please connect to a different account. Questions? Contact [email protected] ."
AP404	Routing number provided does not pass validation	Confirm valid routing number.	"We could not validate your routing number."
AP405	Error adding bank	Confirm valid bank account for user. There may be an issue with bank linking at this time.	"Error adding user bank account."
AP406	Account number provided does not pass validation	Confirm valid account number.	"Invalid account number"
AP407	User flagged as malicious and has been blocked from bank linking	The user may contact the Aeropay Team for a possible override at [email protected]	"Bank linking has been disabled on your account. Please contact [email protected] to resolve."
AP408	Invalid aggregator	Provide a supported aggregator	"Unknown Aggregator {aggregator}"
AP409	Invalid redirectURI	Provide a valid redirectURI	"redirectURI invalid."
AP410	This bank account is already linked to another user	The user may contact the Aeropay Team for a possible resolution at [email protected]	"There was an issue linking your bank account. please contact [email protected] to resolve."
AP411	Invalid account type	User may have connected a non-checking account. Ensure checking account is linked.	"Invalid account connected for processing payments. Please connect a checking account."
AP412	Bank account has been removed from users account	Provide valid bankAccountId or remove bankAccountId param and transaction will use user's default bank account	"This account has already been removed.."
AP413	Bank account does not belong to merchant	Merchant bank account may not be valid. Reach out to Aeropay representative.	"Bank account {account} does not belong to merchant {merchant}."
AP414	Bank linking limit reached	User has already linked 5 unique accounts.	"Sorry, you've linked the maximum number of accounts to your Aeropay profile. Please reach out to [email protected] if you have any questions."
AP415	Bank linking limit reached	User has already linked this routing + accounting combination 3 times before.	"Sorry, you've already linked this bank account before. Please reach out to [email protected] if you have any questions."
AP500	Outstanding micro deposit	Confirm micro deposit before linking bank.	"Outstanding manual bank link for account ending in {last 4}."
AP501	Microdeposit failed	Unable to create microdeposit. Try again later or reach out to support.	"Unable to create micro deposit for account ending in {last 4}."
AP502	Microdeposit failed	Unable to fetch microdeposit. Try again later or reach out to support.	"Unable to get micro deposit."
AP503	Microdeposit failed	Exceeded max number of allowed micro deposit failures.	"Exceeded maximum number of attempts for account ending in {last 4}.
AP504	Incorrect microdeposit amounts	Provide correct micro deposit amounts.	"At least one of these amounts is incorrect. Please ensure you are entering two different amounts exactly as they appear in your account."
AP505	Microdeposit batch failure	Aeropay is unable to batch the microdeposits. Try another bank or reach out to support.	"'Unable to batch microdeposits."
AP506	Microdeposit batch failure	Aeropay is unable to batch the microdeposits. Try another bank or reach out to support.	"Aeropay is unable to batch the microdeposits. Try another bank or reach out to support."

Subscriptions (AP6XX)

Error Code	Meaning	Resolution	Message
AP600	Error Fetching Subscription(s)	We were not able to locate the subscription(s). Please contact Aeropay for assistance.	"Error Fetching subscription."
AP601	No Subscription for id	There isn't an active subscription associated with the ID provided. Please contact Aeropay for assistance.	"No subscription for id {subscription_id}"
AP602	Missing Subscription Id	The subscription request is missing a subscription ID. Please retry the subscription request with a valid subscription ID.	"A SubscriptionId is required."
AP603	Failed to Fetch Subscription Enrollments	We were not able to pull the requested list of users enrolled in this subscription. Please contact Aeropay for assistance.	"Failed to fetch subscription enrollments."
AP604	Enrollments must be for the specified merchant	Only users on your merchant account can be associated with subscriptions. Please contact Aeropay for assistance.	"Enrollments must be for the specified merchant."
AP605	A Merchant is Required	A merchant ID was not included in the subscription request. Please contact Aeropay for assistance.	"A merchant is required"
AP606	Bank Account attempted to be removed while it still has subscriptions	A user's active bank account cannot be removed if the user is associated with an active subscription. Please remove the user from the subscription before removing the primary bank account.	"Bank Account attempted to be removed while it still has subscriptions"
AP607	Subscription does not belong to the merchantId	The subscription ID provided does not belong to your merchant account. Please contact Aeropay for assistance.	"Subscription #{subscriptionId} does not belong to merchant #{merchantId}."
AP608	Subscription is marked as removed	The subscription ID provided is for an inactive subscription. Please utilize an active subscription ID or contact Aeropay for assistance.	""Subscription #{subscriptionId} is removed."

General/Other Errors (AP700, AP800, AP900)

Error Code	Meaning	Resolution	Message
AP700	Payload is missing required parameter	Include the missing required parameter	"Missing required Parameter: '{parameter}'"
AP800	Shopify integration: access token missing	There is no access token for given scope. Reach out to Aeropay for assistance.	"No access token for shopify scope: {scope}"
AP900	Error calling external API	An issue arose calling an external API. Reach out to Aeropay for assistance.	"Error when calling {api} API, returned with HTTP status code {code}"

Webhooks (AP11XX)

Error Code	Meaning	Resolution	Message
AP1100	Invalid webhook topic	Provide valid topic or webhook Id for webhook delete	"Topic or webhook Id required to delete webhook"
AP1101	Error fetching webhook	Aeropay is unable to fetch webhook. Try again later or contact Aeropay.	"Error fetching webhook"
AP1102	No topic provided	Provide a valid topic for webhook.	"topic required to create webhook"
AP1103	No url provided	Provide a valid url for webhook.	"Url is invalid or missing"
AP1104	Invalid topic	Provide a valid url for webhook.	"Unrecognized topic: {topic}"
AP1105	Error creating webhook	Webhook could not be created. Try again later or contact Aeropay.	"Error creating webhook"
AP1106	Error deleting webhook	Webhook could not be deleted. Try again later or contact Aeropay.	"Error deleting webhook"
AP1107	No merchant provided	Provide a valid merchantId.	"A Merchant is required"

Refunds (AP13XX)

Error Code	Meaning	Resolution	Message
AP1300	Transaction already refunded	Transaction has already been refunded, no refund needs to be issued.	"Transaction #{transaction_id} has already been refunded by Transaction #{reversal_transaction_id}"
AP1301	Refund already queued	Transaction has already been queued for refund, no action needs to be taken.	"Transaction {transaction_id} has already been queued for a refund"
AP1302	Invalid refund amount	Provide refund amount less than or equal to the transaction amount.	"Refund amount must be equal to or less than the original transaction amount"
AP1303	Negative refund amount	Cannot refund a negative amount.	"Refund amount must be positive"
AP1304	Invalid transaction type for refund	Transaction cannot be refunded due to transaction type.	"{transaction_type} transactions cannot be refunded"