Errors and status codes
Environment: Live
Read Moolre response envelopes, distinguish transport errors from API errors, and surface actionable failures to users.
# Errors and status codes
Read Moolre response envelopes, distinguish transport errors from API errors, and surface actionable failures to users.
## Read the response envelope first
Moolre responses include a status value, a code, a message, data, and an optional go value. Use the HTTP status for transport-level handling, then use the response code and message to decide what the application should do next.
Treat successful HTTP responses with an application error payload as an API-level failure. Keep the code and a correlation value in your logs so support can trace the request quickly.
## API status code reference
The following application codes are used across the live and sandbox environments. Use the code as the stable value for branching and logging, and use the message as user-facing context. Always handle the HTTP status separately because an HTTP success response can still contain an application-level failure.
| Code | Response | Condition |
| --- | --- | --- |
| WC02 | Wallet created successfully. Your wallet will be reloaded shortly, or click close to refresh now. | When a wallet is created successfully. |
| AIN01 | Authentication Error | When the API keys or username are incorrect. |
| WCU02 | Account updated successfully. | Not specified in the source catalogue. |
| APGW06 | This currency does not support API. | Not specified in the source catalogue. |
| APGW16 | Wallet updated successfully. | Not specified in the source catalogue. |
| WCU01 | Wallet update failed: invalid account number. | Not specified in the source catalogue. |
| APGW12 | Authentication Error, wallet not found. | When the wallet being updated is not found in your wallets. |
| APGW21 | You already have a wallet with this account name. Please choose a different account name. | When creating a new wallet with an existing account name. |
| APGW00 | Wallet created successfully. | Not specified in the source catalogue. |
| SW01 | Wallet Found | Not specified in the source catalogue. |
| AIN03 | Authentication Error, wallet not found. | When checking account status and the API keys or wallet cannot be found. |
| ST08 | Transactions Found | Not specified in the source catalogue. |
| ST09 | Transactions not Found | Not specified in the source catalogue. |
| AVD01 | Successful | When validating the name for a Ghanaian number. |
| IN01 | Authentication Error | When validating a name with incorrect API keys. |
| OBGH01 | Pay out Successful | When making a payout. |
| APY18 | External reference is required and must be unique. | When making a payout with a missing or non-unique external reference. |
| APY17 | Pay out Failed | Not specified in the source catalogue. |
| APY21 | Insufficient wallet balance. | When making a payout with insufficient wallet balance. |
| TR099 | Internal transfer initiated successfully | When making an internal transfer. |
| OM03 | Pay out Successful | When an internal transfer is completed successfully. |
| TR09 | It looks like you have insufficient balance to make this payment | When the wallet used for an internal transfer has insufficient funds. |
| SS01 | Transaction Successful | When checking a transfer transaction status. |
| TP13 | External reference is required and must be unique. | When receiving mobile money with a missing or non-unique external reference. |
| TR099 | null | Mobile money collection: when the Mobile Money USSD prompt is triggered successfully. |
| TP17 | Phone number verification successful. | Mobile money collection: when OTP verification is successful. |
| TP14 | Please complete the verification process sent to you via SMS and try again. | Mobile money collection: when verifying an OTP. |
| TP01 | Currency Invalid | Mobile money collection: when an unsupported currency is supplied. |
| P02 | Transaction Failed | Payment webhook: a failed payment attempt with status 0 and data.txstatus 2. Read data.reason for the failure reason. |
| OTGH02 | Pay out in Progress | When an unsupported channel is selected. |
| AD14 | Terminal Creation Successful | When creating a Payment ID. |
| AD19 | Account No. Creation Successful | For bank collections. |
| AC01 | Payment ID / Bank Account Found | For a bank account status lookup that finds the account. |
| AC03 | Payment ID / Bank Account Not Found | For a bank account status lookup when the reference or account number is incorrect. |
| POS09 | POS payment link successfully generated. | Not specified in the source catalogue. |
| TP09 | This channel does not support API topup. | For a payment link using an unsupported channel. |
| SMS01 | Success | When an SMS is sent successfully. |
| ASMS07 | Sender ID is not approved. Please log in to app.moolre.com and set up your Sender ID. | When the Sender ID is incorrect, not approved, or does not exist. |
| ASMQ10 | SMS Status | When checking the status of an SMS. |
| ASMQ12 | Sender IDs Created Successfully. | Not specified in the source catalogue. |
| ASMQ08 | Sender ID: '[sender ID]' is longer than 11 characters. | Not specified in the source catalogue. |
| ASMQ01 | Sender ID Status | For approved, pending, or rejected Sender ID statuses. |
| ASMQ08 | List of Your Sender IDs | When listing Sender IDs; the same status code can also be returned when creating one. |
| ASMS09 | Request Unknown. | For an unknown Sender ID request. |
| ASMQ07 | Sender IDs updated successfully. | When approving Sender IDs. |
| ASMQ09 | You do not have permission to update Sender IDs. Contact Customer Support. | Not specified in the source catalogue. |
| ASMQ06 | senderid is required. | Not specified in the source catalogue. |
| ASMQ03 | Account Status | For the SMS service balance. |
| DA01 | sublistid for Ghana Bank Transfer | When retrieving banks. |
| ASB02 | Data bundles | Sales Bundles: a successful bundle catalogue response, grouped by network in the supplied example. |
| WAS200 | Templates retrieved successfully or success | When listing templates, sending a message successfully, or checking message status. |
> **Keep integrations resilient:** Some codes can be returned by more than one operation, and response wording may evolve. Prefer the status code and endpoint context over exact message text. Treat duplicate codes such as TR099 and ASMQ08 as context-dependent.
## Airtime sales codes
ASL11 means the sale is in progress, not that airtime has been delivered. ASL06 is an uncertain outcome: the sale may still have gone through. Check the sale status before retrying; do not generate a new external reference to resubmit a pending or uncertain sale.
Other replies are returned from the sales server unchanged. The table describes code meanings, not guaranteed exact response messages.
| Code | Meaning | Next step |
| --- | --- | --- |
| ASL11 | Sale in progress; no final reply yet. | Check the sale status before treating the top-up as complete or submitting again. |
| ASL00 | Authentication error. | Check the API user and private API key for the wallet. |
| ASL01 | Amount missing or below GHS 1.00. | Provide an amount of at least GHS 1.00. |
| ASL02 | Receiver missing. | Provide the recipient phone number. |
| ASL03 | Incomplete request. | Check all required request fields. |
| ASL04 | Channel not supported. | Use MTN, TELECEL, or AT, or the corresponding legacy value 1, 6, or 7. |
| ASL05 | Type invalid. | Send type 1. |
| ASL06 | Unknown error; the sale may still have gone through. | Confirm the sale status before any retry. Do not generate a new reference to resubmit an uncertain sale. |
| ASL08 | External reference missing or already used. | Use a unique reference per wallet for a new sale. Check the original sale before attempting a duplicate. |
| ASL09 | Currency is not GHS. | Send currency GHS. |
| ASL10 | Wallet currency not supported. | Use a wallet with a supported currency for this GHS sale. |
| ASL12 | Wallet inactive. | Check the wallet activation state. |
| ASL13 | Account number not found. | Check the paying wallet account number. |
- [View the Airtime API](https://docs.moolre.com/api/sales/airtime)
## Data sales codes
Data uses the Airtime Sales codes above, plus the bundle-specific codes below.
Use a bundle ID returned by Bundles for the selected channel network. The bundle price determines the amount charged to the wallet. Do not send an amount parameter.
| Code | Meaning | Next step |
| --- | --- | --- |
| ASL14 | Bundle missing. | Provide a bundle ID returned by Bundles for the selected network. |
| ASL15 | Bundle not sold on this network. | Use a bundle ID that Bundles lists for the selected channel network. |
- [View the Data API](https://docs.moolre.com/api/sales/data)
## Bundle catalogue (ASB02)
ASB02 means Data bundles in the supplied catalogue response. It is a lookup result, not a completed Data purchase.
Use the returned bundle value as the bundle ID in a Data sale, and use the matching network as the sale channel. The bundle price determines the charge; do not send amount to the Data endpoint. An empty network array means this example contains no entries for that network, not that the network is permanently unsupported.
- [View the Bundles API](https://docs.moolre.com/api/sales/bundles)
## Sales Status codes
This endpoint reads Airtime and Data sales records directly. Only sales belonging to the wallet in accountnumber are searched. Use data.txstatus and the application code to distinguish pending, sent, failed-and-refunded, and not-found outcomes. A pending or uncertain purchase must not be treated as delivered or blindly resubmitted with a new reference.
ASS01 means sent, ASS02 failed and refunded, ASS03 pending, and ASS04 not found. refundid identifies the refund transaction for a failed/refunded sale.
| Code | Meaning | Next step |
| --- | --- | --- |
| ASS01 | Sent. | The sale was sent; read data.txstatus and the recorded sale details. |
| ASS02 | Failed and refunded. | Read refundid for the refund transaction. |
| ASS03 | Pending. | Check the status again before treating the sale as complete or retrying a purchase. |
| ASS04 | Not found. | Check accountnumber, idtype, and id; only sales belonging to that wallet are searched. |
| ASS05 | Identifier type invalid. | Use idtype 1, 2, or 3 with the corresponding identifier. |
| ASS06 | Parameters incomplete. | Supply type, accountnumber, idtype, and id. |
| ASS07 | Type invalid. | Send type 1. |
| ASS08 | Unknown error. | The lookup did not establish a final outcome. Do not assume the purchase failed or automatically resubmit it. |
| ASS00 | Authentication error. | Check X-API-USER and X-API-KEY for the selected wallet and environment. |
- [View the Sales Status API](https://docs.moolre.com/api/sales/status)
## Failed payment callbacks (P02)
P02 means Transaction Failed. In a failed payment callback, status is 0 and data.txstatus is 2. This is an application-level outcome code, not an HTTP status code.
Use data.reason to understand the failure and data.externalref to identify the payment attempt. data.transactionid can be null, and amount and value can be zero-valued strings. Do not mark the payment as paid or fulfil an order from a failed callback.
- [View the failed payment callback example](https://docs.moolre.com/api/payments/webhook#failed-callback)