Error Codes

The Direct Debit API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

codes in the 2xx range indicate success
codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a header is missing, etc.)
codes in the 5xx range indicate an error with Ayoconnect or the bank's system (these are rare but they happen).

As our API can raise errors for many reasons, such as a failed charge, invalid parameters, authentication errors.. we recommend writing code that gracefully handles all possible error codes.

All the errors include an error code and a short human-readable message that briefly explains the error reported (you can use it internally but don't share it with your clients/users).

Error responses

Error responses are a combination of the HTTP response code, the service code, and the case dode.

Error response = HTTP response code + service code + case code

Service Codes

Below is a list with all the service codes:

Service code	Service
00	Callback API
10	Generate B2B Access Token API
20	Generate B2B2C Customer Authorization Token API
30	Get Oauth Code API
31	Account Binding API
32	Account Unbinding API
33	Direct Debit Payment API
34	Verify OTP API
35	Get a List of Cards Bound to a Customer API
36	Get the Status of a transaction API

HTTP Response Codes

Below is a list of possible HTTP response codes, along with additional information about them:

HTTP Response	Message	Description
400	Bad Request	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
401	Unauthorized	Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
403	Forbidden	The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
404	Not Found	The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client.
405	Method Not Allowed	This means the server is refusing to accept the request because the specific HTTP method (e.g., GET, POST, PUT, DELETE) used is not permitted for that particular URL or resource.
409	Conflict	This response is sent when a request conflicts with the current state of the server.
429	Too Many Requests	The user has sent too many requests in a given amount of time.
500	Internal Server Error	The server has encountered a situation it does not know how to handle.
504	Gateway Timeout	This error response is given when the server is acting as a gateway and cannot get a response in time.

Case Codes

Below is a list of all possible HTTP response codes and case codes, along with additional information about them:

HTTP Code	Service Code	Case Code	Response Message	Description of the error:	Recommendation
400	XX	00	Bad Request	Bad Request	Retry
400	XX	01	Invalid Field Format `{fieldName}`	`{fieldName}` is invalid. Check the format / value of field	Retry with correct format.
400	XX	02	Invalid Field Format `{fieldName}`	`{fieldName}` is invalid. Check the format / value of field	Retry with correct format
400	XX	03	Bad Request	Bad Request	Retry
401	XX	00	Unauthorized	Invalid Authorization-Customer Header /	Retry
401	XX	00	Unauthorized	Invalid mandatory header X-SIGNATURE	Retry
401	XX	00	Unauthorized	Invalid Authorization Header	Retry
401	XX	01	Invalid Token (B2B)	Invalid Token (B2B).	Retry with correct credentials
401	XX	02	Invalid Customer Token	Customer token is invalid.	Unbind the account (Unbinding API)
401	XX	03	Token Not Found (B2B)	Token Not Found (B2B).	Retry with correct credentials
401	XX	04	Customer Token Not Found	Token not found in the system. This occurs on any API that requires token as input parameter.	Raise to Ayoconnect support team
403	XX	00	Session Expired	Session expired. Please try again	Retry
403	XX	00	Too many Requests	The OTP requests have reached the maximum	Retry after some time
403	XX	01	Feature Not Allowed	Feature Not Allowed At This Time.	Retry after some time
403	XX	02	Exceeds Transaction Amount Limit	Exceeds Transaction Amount Limit.	Retry after some time
403	XX	03	Suspected Fraud Transaction	Suspected Fraud.	Inform customer that their binded card/account has been flagged for suspicious activity and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
403	XX	04	Activity Count Limit Exceeded	Retry count exhausted. Please try after some time	Retry after some time
403	XX	05	Do Not Honor	The customer is blocked / Card account has been frozen / Maximum (OTP) passcode retries have been attempted. The customer is blocked	Raise to Ayoconnect support team
403	XX	05	Card Blocked	The Card is blocked.	Raise to Ayoconnect support team
403	XX	06	Feature Not Allowed At This Time	Feature Not Allowed At This Time.	Retry after some time
403	XX	07	Card Blocked	Card is blocked or temporarily disabled by bank	Inform customer that their binded card/account has been blocked and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
403	XX	08	Card Expired	Card has expired	Inform the customer that their binded card/account has expired and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
403	XX	09	Dormant Account	The account is dormant.	Inform the customer their binded card/account is dormant and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
403	XX	10	Need To Set Token Limit.	Need To Set Token Limit.	Raise to Ayoconnect support team
403	XX	11	OTP Blocked	OTP has been blocked.	Retry after some time
403	XX	12	OTP Lifetime Expired	The (OTP) passcode has expired	Retry
403	XX	13	OTP Sent To Cardholder	OTP is already sent
403	XX	14	Insufficient Funds	Insufficient Funds	Inform the customer their binded card/account does not have sufficient funds to process the transaction, and then retry
403	XX	15	Transaction Not Permitted	Transaction Not Permitted.	Retry
403	XX	16	Suspend Transactions	An error occurred while performing the transaction using the card	Retry
403	XX	17	Token Limit Exceeded	Purchase amount exceeds the token limit set prior	Raise to Ayoconnect support team
403	XX	18	Inactive Card/Account/Customer	Inactive Account.	Inform the customer their binded card/account is inactive and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
403	XX	18	Inactive Card	Card is inactive	Inform the customer their binded card/account is inactive and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
403	XX	18	Inactive Customer	The customer is inactive.	Inform the customer their binded card/account is inactive and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
403	XX	19	Technical occurred from bank, please check with our customer support team.	Technical occurred from bank, please check with our customer support team.	Retry
403	XX	20	Transaction Limit Exceeded	Exceeds Transaction Amount Limit	Retry after some time
403	XX	20	Transaction Failed	Payment without OTP is not allowed for this amount	Retry with proper OTP configuration
403	XX	20	Transaction Failed	Amount is lesser than the merchant limit	Retry with proper amount
403	XX	20	Transaction Failed	Payment with OTP requires minimum amount	Retry with proper amount
403	XX	20	Transaction Failed	Payment without OTP is not allowed for this amount	Retry with proper OTP configuration
403	XX	21	Set Limit Not Allowed	Set Limit Not Allowed.	Raise to Ayoconnect support team
403	XX	22	Token Limit Invalid	Token Limit Invalid.	Raise to Ayoconnect support team
403	XX	23	Invalid Transaction	Invalid Transaction from bank	Retry
404	XX	00	Invalid Transaction Status	The transaction status is invalid	Retry
404	XX	01	Transaction Not Found	Transaction Not Found	Retry. Raise to Ayoconnect support team if issue persists
404	XX	02	Invalid Token	The bank card token or account token is invalid/expired	Unbind the account (Unbinding API)
404	XX	02	Invalid XExternalId	Invalid mandatory parameter XExternalId	Retry with proper X-External-ID value
404	XX	03	Bank Not Supported	Operation could not be performed because the bank is inactive	Raise to Ayoconnect support team
404	XX	06	Need To Request OTP	Need To Request OTP	Retry after 24 hours
404	XX	07	Invalid publicUserId	The publicUserId is invalid	Raise to Ayoconnect support team
404	XX	08	Inactive Merchant	Merchant is inactive	Raise to Ayoconnect support team
404	XX	08	Invalid Merchant	Merchant not found	Raise to Ayoconnect support team
404	XX	08	Invalid Merchant	The merchantId is invalid	Raise to Ayoconnect Support team
404	XX	11	Invalid Card	Card number is invalid	Inform the customer their binded card/account has an issue and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
404	XX	11	Invalid Card	Card was not found	Inform the customer their binded card/account has an issue and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
404	XX	11	Invalid Customer	Customer not found	Inform the customer their binded card/account has an issue and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
404	XX	11	Invalid Customer	Merchant and Customer details are mismatched	Inform the customer their binded card/account has an issue and customer would need to contact their bank. If no action from customer, unbind the account (Unbinding API)
404	XX	13	Invalid Amount	The amount is invalid	Raise to Ayoconnect support team
404	XX	15	Invalid OTP	The (OTP) passcode is incorrect	Retry with correct OTP
404	XX	15	Invalid OTP	The otpToken is invalid	Retry with correct OTP
404	XX	15	Invalid OTP	The (OTP) passcode is invalid	Retry with correct OTP
404	XX	16	Partner Not Found	Partner Not Found	Raise to Ayoconnect support team
404	XX	17	Invalid Terminal	Invalid Terminal	Raise to Ayoconnect support team
404	XX	18	Inconsistent Request	Inconsistent Request Parameter.	Raise to Ayoconnect support team
405	XX	00	Requested Function Is Not Supported	Payment with OTP is not supported at this time	Raise to Ayoconnect support team
405	XX	01	Requested Operation Is Not Allowed	Requested operation is not allowed at this time	Retry after some time
409	XX	00	Conflict	Cannot use same 'X-EXTERNAL-ID' in different flow	Retry with proper X-External-ID value
409	XX	01	Duplicate partnerReferenceNo	Transaction has previously been processed indicates the same partnerReferenceNo already success.	Retry with proper partnerReferenceNo
429	XX	00	Too Many Requests	The OTP requests have reached the maximum	Retry after some time
500	XX	00	General Error	General Error	Retry. Raise to Ayoconnect support team if issue persists
500	XX	00	Technical error from Ayoconnect, please check with our customer support.	Technical error from Ayoconnect, please check with our customer support.	Retry. Raise to Ayoconnect support team if issue persists
500	XX	02	Internal Server Error	Internal Server Error from bank	Retry. Raise to Ayoconnect support team if issue persists
500	XX	03	Transaction Failed	A bank error occurred while performing this operation	Retry. Raise to Ayoconnect support team if issue persists
504	XX	00	Timeout	Server Timeout	Retry. Raise to Ayoconnect support team if issue persists
504	XX	00	Timeout	Bank gateway timeout	Retry. Raise to Ayoconnect support team if issue persists