Disbursement Errors
Common Errors in Disbursements
Below is a list of common errors you may encounter while using our Disbursements APIs . For simple understanding, we’ve split them into 2 categories:
- Errors in creating the disbursement
- Errors in executing the disbursement
Errors in Creating the Disbursement
If you receive an error in our API response, this means that there were issues creating the disbursement due to invalid inputs or issues with the server.
| Error Code | Explanation |
| API_VALIDATION_ERROR INVALID_JSON_FORMAT BANK_CODE_NOT_SUPPORTED_ERROR RECIPIENT_ACCOUNT_NUMBER_ERROR | Certain inputs do not meet our API validation requirements. |
| RECIPIENT_AMOUNT_ERROR MAXIMUM_TRANSFER_LIMIT_ERROR | Every channel has a minimum and maximum transaction amount. We will return an error response if the transfer amount requested does not conform to the prescribed limits. See Disbursement Limits. |
| DUPLICATE_TRANSACTION_ERROR | Idempotency key has been used before. Use a unique idempotency key and try again. Learn more here |
| REQUEST_FORBIDDEN_ERROR | API key in use does not have necessary permissions to perform the request. Please assign proper permissions for the key. Learn more here |
| SERVER_ERROR | There was an error connecting to our server when you were attempting to create a disbursement request. If you used an idempotency key in the original request, you may retry this safely using the same idempotency key. Otherwise, please check if the disbursement has already been created in our system before deciding whether to try again. You can do so by checking for the disbursement on your Dashboard or via the Get disbursement by external_id API. If the disbursement has not been created, please retry the disbursement request in 1-2 hours. |
Errors in Executing the Disbursement
If you receive a failed disbursement in the callback, this means that we tried processing the disbursement and failed.
We return failure codes in our callbacks where disbursements fail for any reason. It is important that you understand each failure code in detail in order to decide on the appropriate action to take. Below is a comprehensive list of the possible failure codes that you may receive, what they mean and what our corresponding suggested action is.
| Error Code | Explanation | Should you retry? |
|---|---|---|
| INSUFFICIENT_BALANCE | There is insufficient balance in your account to make the disbursement in the desired amount. | Yes, please retry the disbursement after ensuring that you have sufficient balance in your account. |
| UNKNOWN_BANK_NETWORK_ERROR | The bank has delivered an error they have not documented. By definition, this means the bank does not know the issue. | Unfortunately, we are unable to predict whether the disbursement will succeed should you retry the same disbursement request. You may however choose to retry the same disbursement request at least one hour after receiving our callback at your own discretion. |
| TEMPORARY_BANK_NETWORK_ERROR | We have hardwired routine bank downtime in our system and queue requests received during this period so that they may be disbursed as soon as bank servers are back up again. However, Indonesian banks regularly experience unexpected downtime that typically last 1-3 hours. These may be caused by unexpected maintenance or data centres going down. | Yes, please retry the disbursement in 1-3 hours. |
| SWITCHING_NETWORK_ERROR | Switching networks provide the underlying payments rails for instant transfers. As such, when the switching network provider is having issues, the fund transfer will fail. In some cases, you will receive this error when the destination account is inactive or the bank has blocked the account. | Please retry after confirming with the beneficiary that the destination bank account exists and is able to receive funds. If the account is indeed active, please retry the disbursement in 1-3 hours. |
| INVALID_DESTINATION | This error occurs when a banking channel tells us an account is invalid. Typically, this means that the account is not yet registered at the destination bank or the bank has blocked the account. This also occurs for newly created bank accounts which have yet to be updated to national databases. | You are unlikely to succeed if you retry the same disbursement request. Please confirm with the beneficiary that the destination bank account details are correct. Please revise the request to correct the problem before trying again. |
| REJECTED_BY_BANK or REJECTED_BY_CHANNEL | The switching network or destination partner can reject fund transfers for a variety of reasons, including issues with the beneficiary account's ability to receive funds. | Please retry after confirming with the beneficiary that the destination bank account exists and is able to receive funds. For e-wallets, common root cause is when amount exceeds destination account balance limit. E-wallets usually impose a maximum limit on each user's account balance. Please retry after confirming that the destination account is able to recieve the disbursement amount. |
| TRANSFER_ERROR | We’ve encountered a fatal error while processing this disbursement. Normally, this means that certain API fields in your request are invalid. | It is unlikely that the same disbursement request will succeed if you retry. |
| TEMPORARY_TRANSFER_ERROR | We’ve encountered an issue while attempting to process this disbursement. From experience, this issue should be resolved within the next 1-2 hours. | Yes, please retry the disbursement in 1-2 hours. |
| EMPTY_ACCOUNT_NAME | Account name was not included in the disbursement. | The account name is required to be filled. You are safe to retry the disbursement by including the Account Name |
We recommend that you follow each recommended retry time frame precisely. You should also implement a maximum number of retries.
Last Updated on 2023-05-24