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:
400	XX	00	Bad Request	Bad Request
400	XX	01	Invalid Field Format `{fieldName}`	`{fieldName}` is invalid. Check the format / value of field
400	XX	02	Invalid Field Format `{fieldName}`	`{fieldName}` is invalid. Check the format / value of field
400	XX	03	Bad Request	Bad Request
401	XX	00	Unauthorized	Invalid Authorization-Customer Header /
401	XX	00	Unauthorized	Invalid mandatory header X-SIGNATURE
401	XX	00	Unauthorized	Invalid Authorization Header
401	XX	01	Invalid Token (B2B)	Invalid Token (B2B).
401	XX	02	Invalid Customer Token	Customer token is invalid.
401	XX	03	Token Not Found (B2B)	Token Not Found (B2B).
401	XX	04	Customer Token Not Found	Token not found in the system. This occurs on any API that requires token as input parameter.
403	XX	00	Session Expired	Session expired. Please try again
403	XX	00	Too many Requests	The OTP requests have reached the maximum
403	XX	01	Feature Not Allowed	Feature Not Allowed At This Time.
403	XX	02	Exceeds Transaction Amount Limit	Exceeds Transaction Amount Limit.
403	XX	03	Suspected Fraud Transaction	Suspected Fraud.
403	XX	04	Activity Count Limit Exceeded	Retry count exhausted. Please try 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
403	XX	05	Card Blocked	The Card is blocked.
403	XX	06	Feature Not Allowed At This Time	Feature Not Allowed At This Time.
403	XX	07	Card Blocked	Card is blocked or temporarily disabled by bank
403	XX	08	Card Expired	Card has expired
403	XX	09	Dormant Account	The account is dormant.
403	XX	10	Need To Set Token Limit.	Need To Set Token Limit.
403	XX	11	OTP Blocked	OTP has been blocked.
403	XX	12	OTP Lifetime Expired	The (OTP) passcode has expired
403	XX	13	OTP Sent To Cardholder	OTP is already sent
403	XX	14	Insufficient Funds	Insufficient Funds
403	XX	15	Transaction Not Permitted	Transaction Not Permitted.
403	XX	16	Suspend Transactions	An error occurred while performing the transaction using the card
403	XX	17	Token Limit Exceeded	Purchase amount exceeds the token limit set prior
403	XX	18	Inactive Card/Account/Customer	Inactive Account.
403	XX	18	Inactive Card	Card is inactive
403	XX	18	Inactive Customer	The customer is inactive.
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.
403	XX	20	Transaction Limit Exceeded	Exceeds Transaction Amount Limit
403	XX	20	Transaction Failed	Payment without OTP is not allowed for this amount
403	XX	20	Transaction Failed	Amount is lesser than the merchant limit
403	XX	20	Transaction Failed	Payment with OTP requires minimum amount
403	XX	20	Transaction Failed	Payment without OTP is not allowed for this amount
403	XX	21	Set Limit Not Allowed	Set Limit Not Allowed.
403	XX	22	Token Limit Invalid	Token Limit Invalid.
403	XX	23	Invalid Transaction	Invalid Transaction from bank
404	XX	00	Invalid Transaction Status	The transaction status is invalid
404	XX	01	Transaction Not Found	Transaction Not Found
404	XX	02	Invalid Token	The bank card token or account token is invalid/expired
404	XX	02	Invalid Action	Invalid mandatory parameter action
404	XX	02	Invalid XExternalId	Invalid mandatory parameter XExternalId
404	XX	03	Bank Not Supported	Operation could not be performed because the bank is inactive
404	XX	06	Need To Request OTP	Need To Request OTP
404	XX	07	Invalid publicUserId	The publicUserId is invalid
404	XX	08	Inactive Merchant	Merchant is inactive
404	XX	08	Invalid Merchant	Merchant not found
404	XX	08	Invalid Merchant	The merchantId is invalid
404	XX	11	Invalid Card	Card number is invalid
404	XX	11	Invalid Card	Card was not found
404	XX	11	Invalid Customer	Customer not found
404	XX	11	Invalid Customer	Merchant and Customer details are mismatched
404	XX	13	Invalid Amount	The amount is invalid
404	XX	15	Invalid OTP	The (OTP) passcode is incorrect
404	XX	15	Invalid OTP	The otpToken is invalid
404	XX	15	Invalid OTP	The (OTP) passcode is invalid
404	XX	16	Partner Not Found	Partner Not Found
404	XX	17	Invalid Terminal	Invalid Terminal
404	XX	18	Inconsistent Request	Inconsistent Request Parameter.
405	XX	00	Requested Function Is Not Supported	Payment with OTP is not supported at this time
405	XX	01	Requested Operation Is Not Allowed	Requested operation is not allowed at this time
409	XX	00	Conflict	Cannot use same 'X-EXTERNAL-ID' in different flow
409	XX	01	Duplicate partnerReferenceNo	Transaction has previously been processed indicates the same partnerReferenceNo already success.
429	XX	00	Too Many Requests	The OTP requests have reached the maximum
500	XX	00	General Error	General Error
500	XX	00	Technical error from Ayoconnect, please check with our customer support.	Technical error from Ayoconnect, please check with our customer support.
500	XX	02	Internal Server Error	Internal Server Error from bank
500	XX	03	Transaction Failed	A bank error occurred while performing this operation
504	XX	00	Timeout	Server Timeout
504	XX	00	Timeout	Bank gateway timeout