Error Handling
Common Errors in Payouts
Below is a list of common errors you may encounter while using our Payouts APIs . For simple understanding, we’ve split them into 2 categories:
- Errors in creating the payout
- Errors in executing the payout
Errors In Creating the Payout
If you receive an error in our API response, this means that there were issues creating the payout due to invalid inputs or issues with the server.
| Error Code | Explanation |
|---|---|
| API_VALIDATION_ERROR INVALID_JSON_FORMAT CHANNEL_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 Payout
If you receive a failed payout in the callback, this means that we tried processing the payout and failed. We return failure codes in our callbacks where payouts 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 Message | Description | Should you retry? |
|---|---|---|
| INSUFFICIENT_BALANCE | Client has insufficient balance for the payout amount. | Yes, retry the payout after ensuring that you have sufficient balance in your account. |
| INVALID_DESTINATION | Destination account does not exist/is invalid. | You are unlikely to succeed if you retry the payout request. Please confirm with the beneficiary whether the destination account is correct |
| REJECTED_BY_CHANNEL | Payout failed due to an error from the destination channel. This is usually because of network issues associated with the destination bank or issues crediting funds into the destination bank account | Yes, retry the payout after validating that the destination bank account number is active and can receive funds in your chosen currency. |
| TEMPORARY_TRANSFER_ERROR | The channel networks are experiencing a temporary error. Retry the payout in 1-3 hours. | Yes, retry the payout in 1-3 hours. |
| TRANSFER_ERROR | We’ve encountered a fatal error while processing this payout. 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. |
| 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. |
Last Updated on 2023-07-25