The Hubtel Sales API uses standard HTTP error reporting. Successful requests return HTTP status codes in the 2xx. Failed requests return status codes in 4xx and 5xx. Response codes are included in the JSON response body, which contain information about the response.
| Response Code | Description | Required Action |
|---|---|---|
| 0000 | The transaction has been processed successfully | None |
| 0001 | Request has been accepted. A callback will be sent on final state | None |
| 0005 | There was an HTTP failure/exception when reaching the payment partner | The transaction state is not known. Please contact Retail Systems Engineer to confirm the status of this transaction |
| 2001 | Transaction failed due to an error with the Payment Processor. Please review your request or retry in a few minutes | • Customer either entered no or invalid PIN • Mobile network not able to parse your request. • USSD session timeout. • Having strange characters (&*!%@) in your description. |
| 2100 | The request failed as the customer's phone is switched off. | None |
| 2101 | The transaction failed as the PIN entered by the Airtel Money customer is invalid | None |
| 2102 | The Airtel Money user has insufficient funds in wallet to make this payment | None |
| 2103 | The mobile number specified is not registered on Airtel Money | None |
| 2050 | The MTN Mobile Money user has insufficient funds in wallet to make this payment. | Customer has to top up mobile money wallet with funds more than the amount being charged. |
| 2051 | The mobile number provided is not registered on MTN Mobile Money | Ensure that the mobile number is registered on the MTN channel. |
| 2152 | The mobile number specified is not registered on Tigo cash. | None |
| 2153 | The amount specified is more than the maximum allowed by Tigo Cash | None |
| 2154 | The amount specified is more than the maximum daily limit allowed by Tigo Cash. | None |
| 2200 | The recipient specified is not registered on Vodafone Cash. | None |
| 2201 | The customer specified is not registered on Vodafone Cash. | None |
| 3008 | The customer specified is not registered on Vodafone Cash. | The payment channel has been disabled on your account. Ensure you have uploaded your business registration documents for your account to be duly verified. Contact your Retail Systems Engineer with your Merchant Account Number if you are receiving this error even though you have provided the necessary documents. |
| 3009 | Merchant account is not available. | Check to confirm if your merchant account number is valid. |
| 3012 | You have insufficient funds in your Merchant Account | Amount is less than funds in merchant account |
| 3013 | Amount specified is less than the fees. | The amount you're charging is less than the fee. See the fees charged on a transaction here. |
| 3022 | Merchant account has been registered on this channel, but the channel has not been activated. | None |
| 3024 | Specified Channel Provider is invalid | The selected payment channel is invalid |
| 4000 | Validation errors | Validation errors. Something is not quite right with this request. Please check again. |
| 4075 | Insufficient prepaid balance | You don't have enough funds in your prepaid balance to send money to your customers. You can top-up your prepaid balance by transferring funds from your available balance or bank deposit. |
| 4080 | Insufficient available balance | None |
| 4101 | Authorization for request is denied | Ensure that you're providing the correct Basic Auth key for the Authorization header. Also ensure you’re passing your POS Sales number in the endpoint |
| 4103 | Permission denied | You are not allowed to perform this transaction. Kindly ensure your API keys are accurate. |
| 4105 | Authenticated Hubtel organization is not owner of specified account number. | There's a mismatch of the Merchant Account number and the Basic Authorization key. Ensure your API keys are from the same Unity account as the Merchant Account |
| 4505 | Transaction has already been refunded | None |