Common Errors for Declined API Transaction

Modified on Mon, 21 Aug 2023 at 03:45 AM

In API transactions, it's important to be aware of common errors that can result in transaction declines. This article highlights some of the common errors encountered during API transactions and provides insights on resolving them effectively.

Table of Contents

Common errors that usually happen in API transactions are typically displayed in the payload response we send, specifically in the error_message fields, providing valuable information for troubleshooting and resolution. Here is the list of error messages encountered when your API transaction got declined. 

Error messages for declined API transaction

Error Message


Invalid destination account number

This error occurs when the sender inputs an incorrect or non-existent account number for the recipient. As a result, the recipient's account cannot be found, leading to the transaction being declined. It is crucial to double-check and ensure the accuracy of the account number provided to avoid this error. You can use our endpoint validation account number.

Timeout error by bank

A timeout error by the bank indicates that the bank took longer than the allowed time to process the transaction request. This can be due to various factors, such as high server load or technical issues at the bank's end. To handle this, you can retry the transaction after a certain period. 

Unique reference number violation

This error occurs when the reference number used for the transaction is not unique. Each transaction should have a unique reference number to ensure proper identification and tracking. To resolve this, generate a new reference number for the transaction, ensuring it is unique and not used in any previous transactions. Read more in this article.

Bank cannot authenticate the request

This error occurs when the bank is experiencing temporary issues or downtime. Please contact us for further information and assistance in resolving the issue.

Payload validation failed

Payload validation failed error occurs when the data provided in the transaction request does not meet the required validation rules or format. Review the payload data, ensure it is correctly structured and adheres to the API documentation's specifications. Make any necessary adjustments to the payload and retry the transaction.

Rejected by Bank

This error indicates that the bank has explicitly rejected the transaction, possibly due to security reasons or compliance issues. To address this, review the rejection reason provided by the bank and take appropriate actions based on their instructions.

Understanding the common errors that can occur during API transactions is crucial for ensuring a smooth and successful payment process. By being aware of these errors and their possible causes, you can troubleshoot and resolve issues more effectively. For a more comprehensive list of common errors and detailed explanations, please visit this document. Should you encounter any difficulties or require further assistance, please don't hesitate to reach out to our support team. We are here to help you navigate through any challenges and ensure a seamless API transaction experience.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article