Airtel Money · Error reference
Airtel Money's Open API returns a transaction status (TS, TF, TIP, TA) plus response codes. Its error codes are less consistently documented than MTN's or Safaricom's, so this page shows how well each one is confirmed.
Have a response you don't understand? Paste it into the Payment Error Code Lookup and it finds every known code inside.
Each code below is labelled by how well it is documented. Of the 22 codes on this page: 2 are confirmed by several independent sources, and 20 are reported by only one source. Treat codes marked "Reported by one source" as a strong hint, and log the full response so you can check.
The status values that tell you whether the customer paid.
PaidSeen in: Status / callbackRetry: not neededConfirmed by several sources
The customer approved and the money moved.
What to do
Sources: McTaba: Airtel Money API integration (Kenya) · Salami Gateway: Airtel Money SDK docs
WaitingSeen in: Status / callbackRetry: Check the status before retryingReported by one source
The customer hasn't finished approving yet.
What to do
Not known yetSeen in: Status / callbackRetry: Check the status before retryingReported by one source
Airtel isn't sure of the outcome yet.
How to fix it
Why a payment did not go through.
Not paidSeen in: Status / callbackRetry: Yes, as a new requestConfirmed by several sources
The customer declined, didn't have enough money, or the prompt timed out.
How to fix it
Sources: McTaba: Airtel Money API integration (Kenya) · Salami Gateway: Airtel Money SDK docs
Request errorSeen in: Status / callbackRetry: Later, it is temporaryReported by one source
Airtel Money is temporarily unavailable.
How to fix it
Not paidSeen in: Status / callbackRetry: Yes, as a new requestReported by one source
The customer's wallet doesn't have enough money for this payment.
How to fix it
Not paidSeen in: Status / callbackRetry: No, fix the cause firstReported by one source
The amount is below the minimum allowed for this transaction.
How to fix it
Not paidSeen in: Status / callbackRetry: No, fix the cause firstReported by one source
The amount is above the maximum allowed.
How to fix it
Not paidSeen in: Status / callbackRetry: No, fix the cause firstReported by one source
Airtel couldn't match the number to a single account.
How to fix it
Not paidSeen in: Status / callbackRetry: No, fix the cause firstReported by one source
The phone number is not valid.
How to fix it
Not paidSeen in: Status / callbackRetry: Yes, as a new requestReported by one source
The transaction ran out of time before completing.
How to fix it
Returned straight away when the API rejects your request.
WaitingSeen in: API responseRetry: Check the status before retryingReported by one source
Seen with "SUCCESS" on the collection response. Airtel received your request. It does not mean the customer has paid.
What to do
Request errorSeen in: API responseRetry: No, fix the cause firstReported by one source
A general error. Often wrong credentials.
How to fix it
Reported for Airtel Tanzania. Codes may differ in other Airtel countries.
Request errorSeen in: API responseRetry: Later, it is temporaryReported by one source
Airtel Money is temporarily down.
How to fix it
Reported for Airtel Tanzania. Codes may differ in other Airtel countries.
Request errorSeen in: API responseRetry: No, fix the cause firstReported by one source
Request parameters are incorrect.
How to fix it
Reported for Airtel Tanzania. Codes may differ in other Airtel countries.
Not paidSeen in: API responseRetry: No, fix the cause firstReported by one source
The number isn't registered on Airtel Money.
How to fix it
Reported for Airtel Tanzania. Codes may differ in other Airtel countries.
Not paidSeen in: API responseRetry: Yes, as a new requestReported by one source
The customer's balance is too low.
How to fix it
Reported for Airtel Tanzania. Codes may differ in other Airtel countries.
Not paidSeen in: API responseRetry: Yes, as a new requestReported by one source
The amount is above the customer's per-transaction limit.
How to fix it
Reported for Airtel Tanzania. Codes may differ in other Airtel countries.
Request errorSeen in: API responseRetry: Later, it is temporaryReported by one source
The customer has reached their daily limit.
How to fix it
Reported for Airtel Tanzania. Codes may differ in other Airtel countries.
Not paidSeen in: API responseRetry: Yes, as a new requestReported by one source
The customer didn't respond to the USSD prompt in time.
How to fix it
Reported for Airtel Tanzania. Codes may differ in other Airtel countries.
Not paidSeen in: API responseRetry: No, fix the cause firstReported by one source
Too many wrong PIN attempts.
How to fix it
Reported for Airtel Tanzania. Codes may differ in other Airtel countries.
Not paidSeen in: API responseRetry: Yes, as a new requestReported by one source
This transaction ID was already processed.
How to fix it
Reported for Airtel Tanzania. Codes may differ in other Airtel countries.
Map each outcome code to one of four actions. Unknown codes fall back to "check the status", so a new or misspelled code never fulfils or cancels an order by accident.
// What to do with each Airtel Money outcome code.
// Unknown codes fall back to "check_status": never fulfil or fail an order on a code you don't recognise.
const ACTIONS = {
"TS": "fulfil", // Transaction successful
"TF": "mark_failed", // Transaction failed
"TIP": "wait", // Transaction in progress
"TA": "check_status", // Transaction ambiguous
"DP00800001001": "check_status", // Service unavailable
"DP00800001002": "mark_failed", // Insufficient funds
"DP00800001003": "mark_failed", // Amount below minimum
"DP00800001004": "mark_failed", // Amount above maximum
"DP00800001005": "mark_failed", // Account not uniquely identified
"DP00800001006": "mark_failed", // Invalid MSISDN
"DP00800001007": "mark_failed", // Transaction timed out
};
export function airtelNextStep(code) {
const key = String(code ?? "").trim().toUpperCase().replace(/[\s-]+/g, "_");
return ACTIONS[key] ?? "check_status";
}
// Example:
// switch (airtelNextStep(transaction.status_code)) {
// case "fulfil": // verify amount, then mark the order paid (idempotently)
// case "mark_failed": // mark unpaid, show a retry button
// case "wait": // do nothing yet; a callback or your poller will follow
// case "check_status": // ask the status endpoint before deciding
// }
TF (Transaction failed): The customer declined, didn't have enough money, or the prompt timed out. Mark the payment failed. Read the response code or message for the reason, and let the customer retry.
TA (Transaction ambiguous): Airtel isn't sure of the outcome yet. Don't mark it failed or let the customer pay again. Query the status endpoint until it returns TS or TF.
DP00800001006 (Invalid MSISDN): The phone number is not valid. Send the number without the country code (e.g. 752123456 in Uganda). Check it with the phone number formatter.
DP00800001002 (Insufficient funds): The customer's wallet doesn't have enough money for this payment. Ask the customer to top up and try again.
ESB000039 (Transaction timed out): The customer didn't respond to the USSD prompt in time. Let the customer retry and approve the prompt promptly.
Build requests that avoid these errors: Airtel Money Request Builder, Airtel Money collections in Node.js, Airtel Money collections in Laravel.
Checked October 2026. Error codes change. If you see one that's missing or wrong, please let me know.
I integrate MTN MoMo, M-Pesa and Airtel Money into Laravel / PHP, Python / Django, Node.js / Next.js apps: payments, callbacks, payouts and go-live, with tests.