Errors

Learn how our APIs return errors

Asyncpay's APIs are designed to return clear and helpful responses. When an error occurs, the response follows the structure shown below:

{
    "status": "failed",
    "message" "[string]",
    "error": "[string]",
    "error_code": "[string]",
    "error_description": "[string]",
    "error_data": "[object|string]"
}

Response Structure

Every response from the Asyncpay API follows a consistent structure. Here's a breakdown of the fields you may encounter:

Field	Type	Description
status	string	Indicates whether the request was successful. Typically "success" or "failed".
message	string	A short summary message, especially useful when an error occurs.
error	string	A capitalized identifier or codename for the error (e.g. INVALID_SECRET_KEY).
error_code	string or number	A numerical string representing the specific error (e.g. "001").
error_description	string	A more detailed explanation of the error. Often includes tips or guidance to help resolve it.
error_data	object or string	Additional context or data about the error. This is often populated with responses from external services (e.g. Paystack errors) and can help with debugging.

Error Codes Reference

Asyncpay uses standardized error responses to help you quickly understand and debug any issues that occur when interacting with our API. Each error is returned with a clear status code, a descriptive error message, and—where applicable—a machine-readable error identifier and helpful guidance on how to resolve it.

Below is a complete list of error codes you may encounter, along with their meanings and possible causes.

Error	HTTP Status	Code	Description
INVALID_SECRET_KEY	401	001	You have used an invalid format for the Authentication header for accessing our APIs. Our API requires you to set an 'Authentication' header with values: 'Bearer <key>' where the key is your secret key found on your dashboard.
INCORRECT_SECRET_KEY	401	002	You have used an incorrect secret key. Please visit your dashboard and ensure you're using the correct key displayed on your dashboard.
PAYMENT_CHANNEL_NOT_IN_BUSINESS	400	003	Your business does not have a payment channel with the payment_channel provided. Please use a payment channel you have attached to your business or create a new one in your dashboard.
INVALID_REQUEST_STRUCTURE	400	004	The request you supplied to this endpoint does not match the correct structure required. Please consult our documentation for this endpoint, fix the request structure and then try again.
BUSINESS_HAS_NO_PAYMENT_CHANNELS	400	005	The current business does not have any payment channels and cannot continue with this request because of that. Please visit your dashboard to create a payment channel for your business.
INVALID_TRANSACTION_REF	400	006	The transaction reference supplied does not match any transaction in our records. Please ensure the transaction ref is valid.
TRANSACTION_NOT_PENDING	400	007	The endpoint you're trying to access requires the transaction to have a status of pending, but the transaction supplied does not have a status of pending. This usually means the transaction has already been processed before. Please ensure you have the correct reference, and the transaction has not already been processed before.
INVALID_PAYMENT_CHANNEL_SLUG	400	008	You have supplied a payment channel slug that is not supported by Asyncpay. Please ensure you've not made a typo, and also visit our documentation to see the list of payment channels we currently support.
TOO_SMALL_AMOUNT	400	009	You cannot make a transaction with an amount less than 0.01 in value of any currency. Please increase the amount and try again.
ISSUE_WITH_THIRD_PARTY_SERVICE	424	010	There was an issue with performing this action with a third party service provider. Please try again later.
INVALID_CUSTOMER_IDENTIFIER	400	011	The customer identifier you entered is incorrect. This probably happened because no customer exists with the customer_uuid or customer_email supplied in the current business attached to this API key. Please ensure the customer info is correct or create a new customer and try again.
CUSTOMER_EMAIL_ALREADY_EXISTS	400	012	A customer already exists in your business with the email supplied. Please check the request and try again.
DISABLED_PAYMENT_CHANNEL	400	013	The payment channel selected is not enabled. Please enable this payment channel on your dashboard and try again.
INVALID_PAYMENT_REQUEST_REF	400	014	The payment request reference supplied to this endpoint does not match any entity in our records. Please check that it is a valid payment request reference and try again.
BUSINESS_HAS_NO_ENABLED_PAYMENT_CHANNELS	400	015	Your business does not have any enabled payment channels. Please visit your dashboard and enable at least one payment channel to make it possible for your business to carry out transactions.
INCORRECT_PUBLIC_KEY	401	016	You have used an incorrect public key. Please visit your dashboard and ensure you're using the correct key displayed on your dashboard.
INVALID_PUBLIC_KEY	401	017	You have used an invalid format for the public key or provided a wrong public key. Please check for the correct public key found on your dashboard.
INVALID_TRANSACTION_UUID	400	018	The transaction UUID supplied does not match any transaction in our records. Please ensure the transaction UUID is valid.
DUPLICATE_PAYMENT_REQUEST_REFERENCE	400	019	The payment request reference provided already exists on your business. Please provide a unique payment request reference to continue with this request.
INVALID_PAYMENT_REQUEST_CHECKOUT_URL	400	020	The payment request checkout URL provided does not match any payment request in our records. Please ensure the payment request checkout url is valid.
TOO_MANY_REQUESTS	400	021	You have sent too many requests in one minute. Please wait for a minute and try again or contact support if the issue persists or you wish to increase your rate limit.
TEST_PUBLIC_KEY_IN_LIVE_ENV	401	022	You are attempting to use a test public key on a business set to the live environment. Please check for the correct live public key on your dashboard to access the requested resource.
TEST_SECRET_KEY_IN_LIVE_ENV	401	023	You are attempting to use a test secret key on a business set to the live environment. Please check for the correct live secret key on your dashboard to access the requested resource.
LIVE_PUBLIC_KEY_IN_TEST_ENV	401	024	You are attempting to use a live public key on a business set to the test environment. Please check for the correct test public key on your dashboard to access the requested resource.
LIVE_SECRET_KEY_IN_TEST_ENV	401	025	You are attempting to use a live secret key on a business set to the test environment. Please check for the correct test secret key on your dashboard to access the requested resource.
CUSTOMER_ALREADY_SUBSCRIBED_TO_PLAN	400	026	This resource requires the customer not to have an active subscription on the specified subscription plan but the customer is already subscribed to (or in trial for) the specified subscription plan.
INVALID_SUBSCRIPTION_PLAN_UUID	400	027	The subscription plan UUID provided is invalid.
CUSTOMER_NOT_SUBSCRIBED_TO_PLAN	400	028	This resource requires the customer to have an active subscription on the specified subscription plan but the customer is not subscribed to this subscription plan.
SUBSCRIPTION_ALREADY_CANCELLED	400	029	This resource requires the subscription to not have been cancelled but the subscription has already been cancelled.
SUBSCRIPTION_PLAN_NAME_ALREADY_EXISTS	400	030	This resource requires the subscription plan name to be unique but the supplied subscription plan name already exists in your business, check that the name you're supplying is correct and has not already been used and try a different name to continue.
SUBSCRIPTION_ALREADY_ACTIVE	400	031	This resource requires the subscription to be cancelled but the specified subscription is active, please ensure you're supplying the correct UUID or cancel the subscription and try again.
SUBSCRIPTION_PLAN_HAS_ACTIVE_SUBSCRIPTIONS	400	032	This resource requires the subscription plan to have no active subscriptions but the specified subscription plan has active subscriptions, please ensure you're supplying the correct UUID or cancel all subscriptions and try again.
SUBSCRIPTION_PLAN_IS_INACTIVE	400	033	This resource requires the subscription plan to be active but the specified subscription plan is inactive, please ensure you're supplying the correct UUID or activate the subscription plan and try again.
SUBSCRIPTION_PLAN_IS_ACTIVE	400	034	This resource requires the subscription plan to be inactive but the specified subscription plan is active, please ensure you're supplying the correct UUID or deactivate the subscription plan and try again.
SUBSCRIPTION_PLAN_HAS_NO_ACTIVE_SUBSCRIPTIONS	400	035	This resource requires the subscription plan to have active subscriptions but the specified subscription plan has no active subscriptions, please ensure you're supplying the correct UUID or create new subscriptions and try again.
EXPIRED_SUBSCRIPTION_CLAIM	400	036	The subscription claim has expired, please generate a new claim.
INVALID_SUBSCRIPTION_CLAIM	400	037	The subscription claim is invalid, please ensure the claim is correct or generate a new subscription url and try again.
INVALID_PAYMENT_METHOD_UUID	400	038	The payment method UUID supplied is invalid, it probably doesn't exist for the provided customer. Please ensure it is correct and try again.
CANNOT_DELETE_LAST_PAYMENT_METHOD	400	039	You cannot delete the last payment method of a customer, please add a new payment method before deleting this one.
PAYMENT_METHOD_CHARGE_FAILED	400	040	The payment method charge failed, please ensure the payment method is valid and has sufficient funds and try again.
SUBSCRIPTION_PLAN_DOES_NOT_SUPPORT_TRIAL	400	041	The subscription plan does not support trial, please ensure the subscription plan supports trial and try again.
BUSINESS_HAS_NO_NUBAN_PAYMENT_CHANNELS	400	042	Your business is not connected to any payment channels that support NUBAN payouts so you cannot access this resource. Please connect to a payment channel on your dashboard and try again.
BUSINESS_HAS_NO_NUBAN_ACCOUNT_VERIFICATION_PAYMENT_CHANNELS	400	043	Your business is not connected to any payment channels that support verifying NUBAN bank accounts so you cannot access this resource. Please connect to a payment channel on your dashboard and try again.
PAYMENT_CHANNEL_DOES_NOT_SUPPORT_NUBAN_PAYOUT	400	044	The selected payment channel does not support payout to NUBAN accounts. Please use a different payment channel.
PAYMENT_CHANNEL_DOES_NOT_SUPPORT_NUBAN_ACCOUNT_VERIFICATION	400	045	The selected payment channel does not support verifying NUBAN bank accounts. Please use a different payment channel.
INVALID_BANK_CODE	400	046	The bank code supplied is invalid. Please ensure the bank code is correct and try again.
BANK_NOT_AVAILABLE_ON_PAYMENT_CHANNEL	400	047	The bank_code provided is not available on the selected payment channel. Please provide a different bank_code or payment channel and try again.
NUBAN_PAYOUT_RECIPIENT_ALREADY_EXISTS	400	048	A Nuban payout recipient with this bank code and account number already exists. Please use a different bank code and account number to continue.
NUBAN_PAYOUT_RECIPIENT_NOT_FOUND	400	049	The Nuban payout recipient with the specified parameters does not exist. Please ensure the parameters are correct and try again.
INVALID_PAYOUT_REF	400	050	The payout reference supplied to this endpoint does not match any entity in our records. Please check that it is a valid payout reference and try again.
DUPLICATE_PAYOUT_REF	400	051	The payout reference provided already exists on your business. Please provide a unique payout reference to continue with this request.
INVALID_PAYOUT_STATUS	400	052	The payout reference provided already exists on your business. Please provide a unique payout reference to continue with this request.
INVALID_ENDPOINT_FOR_PAYMENT_CHANNEL	400	053	This endpoint doesn't support the payment channel for this resource.
INVALID_PAYOUT_UUID	400	054	The payout UUID supplied does not match any payout in our records. Please ensure the payout UUID is valid.
PAYOUT_NEEDS_TO_BE_FINALIZED	400	055	This payout needs to be finalized before accessing this endpoint. Please finalize the request and try again.
PAYOUT_STILL_PROCESSING	400	056	This payout is still being processed. Please wait for the payout to be processed and try again.
PAYOUT_IS_SUCCESSFUL	400	057	This payout is successful and cannot be modified. Please create a new payout if you need to make changes.
BENEFICIARY_EMAIL_ALREADY_EXISTS	400	058	A beneficiary with this email already exists in your business.
INVALID_CREATE_NUBAN_PAYMENT_METHOD_REQUEST	400	059	Account number and bank code are required to create a NUBAN bank account.
PAYMENT_CHANNEL_NOT_ENABLED	400	060	The selected payment channel is not enabled. Please enable it on your dashboard to continue.
BENEFICIARY_NOT_FOUND	400	061	No beneficiary with these attributes exists in your business.
INVALID_BENEFICIARY_PAYOUT_OPTION_CODE	400	062	No matching beneficiary payment method was found with the supplied code.
PAYOUT_NOT_NUBAN	400	063	This endpoint requires the supplied payout to be of type 'nuban' but the selected payout is not.
INVALID_PAYMENT_CHANNEL_CREDENTIALS	400	064	The payment channel credentials supplied are invalid. Please check the credentials and try again.
CANNOT_TERMINATE_SUBSCRIPTION_BECAUSE_OF_PAYMENTS	400	065	This subscription cannot be terminated because it has payments associated with it.
NO_DEFAULT_PAYMENT_METHOD	400	066	This customer does not have a default payment method set. Please add a payment method before proceeding.
INVALID_BENEFICIARY_PAYOUT_OPTION_UUID	400	067	No matching beneficiary payment method was found with the supplied UUID.
BENEFICIARY_PAYOUT_DESTINATION_NOT_NUBAN	400	068	This beneficiary payout destination is not a NUBAN account.
EXTERNAL_BANK_CODES_REQUIRE_PAYMENT_CHANNELS	400	069	A payment channel slug is required when using an external bank code. Alternatively, use an internal bank code starting with 'NB-'.
SOMETHING_WENT_WRONG	400	070	An error occurred while trying to process your request.
INVALID_BENEFICIARY_TAG_UUID	400	071	The beneficiary tag UUID provided is invalid. Please ensure the tag is correct and try again.
INVALID_BULK_PAYOUT_REQUEST	400	072	The bulk payout request is invalid. Please ensure the request structure is correct and try again.
BULK_PAYOUT_REFERENCE_ALREADY_EXISTS	400	073	A bulk payout with this reference already exists. Please provide a unique reference to continue with this request.
INVALID_BULK_PAYOUT_UUID	400	074	The bulk payout UUID supplied does not match any bulk payout in our records. Please ensure the bulk payout UUID is valid.