Response Codes

Response Structure

The top-up endpoint (POST /adp) returns a code field that indicates the result:

{
  "message": "Descriptive message",
  "statusCode": 200,
  "code": 1,
  "data": { ... }
}

Field	Type	Description
message	string	Human-readable description of the result
statusCode	number	HTTP status code
code	number	Numeric response code (1 for success, other values indicate specific errors)
data	object	Response payload (present on success)

HTTP Status Codes

Status Code	Description
200	Request processed successfully (check code field for top-up results)
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or missing authentication credentials
403	Forbidden — business logic failure (insufficient balance, invalid number, etc.)
404	Not found — requested resource does not exist
500	Internal server error — unexpected error on our side
503	Service unavailable — the service is temporarily offline

Top-up Response Codes

The following response codes may be returned by the POST /adp endpoint:

Code	Message	Description	Resolution
1	Top-up successful! Airtime has been successfully topped up	Success	—
5	The airtime top-up operation has failed	General top-up failure (operator declined for a reason we don't have a specific code for)	Check the transaction via GET /adp/transactions; retry if appropriate
10	The operation is pending and being processed	Transaction is in flight; will reach a terminal state shortly	Poll GET /adp/transactions?extRefId=... for the final state
20	Request declined due to low balance	Insufficient account balance	Top up your account balance in the dashboard
30	Recipient's number is invalid	Phone number format is invalid, destination is not supported, OR the operator rejected the subscriber (not active / not KYC-verified for the requested service)	Verify the phone number is in international format (e.g., 263719545499); for bundles, confirm the recipient is KYC-verified with the operator
50	Repeat recharge to this number within 1 minute is blocked by this provider	The operator blocked a duplicate recharge to the same number within their anti-duplicate window (typically 1 minute)	Wait a minute and retry, or change the amount
90	External reference ID already exists	The extRefId was already used in a previous transaction	Use a unique extRefId for each new transaction
150	Specified amount is invalid	The amount sent does not match what the operator expects for the requested product	If sending a productId, omit amount (the bundle's preset price is used). Re-pull GET /adp/products if your cached catalogue may be stale
190	Customer account not located	Your account could not be found	Verify your API credentials
200	Customer has not been configured to use this service provider	No service configuration for this destination	Contact support to enable the destination
210	Service provider product not found	The productId you sent does not exist (or has been discontinued by the operator)	Re-pull GET /adp/products for the current catalogue
218	The carrier associated with the MSISDN doesn't correspond to the chosen package	The productId is for a different network than the recipient's MSISDN	Use a productId from the recipient's network, or use open-range airtime (omit productId)
221	Data bundle purchase failed	Bundle subscription rejected by the operator	Check the response state; if the recipient is on a non-eligible plan or your catalogue is stale, re-pull GET /adp/products
222	MSISDN verification failed	Unable to verify the recipient's phone number	Verify the phone number and try again
227	Amount is below the minimum allowed recharge amount	Top-up amount is too small	Check the minimum amount for the destination network
228	Amount exceeds the maximum allowed recharge amount	Top-up amount is too large	Reduce the amount or split into multiple transactions
231	Invalid Source Amount	The calculated source amount is below the minimum threshold	Increase the top-up amount
232	Airtime Request is being processed	Returned when processingMode: "ASYNC" is used; the request was queued and will be processed in the background	Poll GET /adp/transactions?extRefId=... for the final state
234	This recharge route is temporarily unavailable	The network provider is experiencing issues	Retry after a few minutes
235	Transaction not found	No transaction matches the lookup criteria	Verify the extRefId / transaction_Id / msisdn you queried

Balance Error Messages

The following error messages may be returned by the GET /adp/balances endpoints:

Message	Description	Resolution
Account not found	The specified account_id does not exist or is not accessible	Verify the account ID from GET /adp/balances
Invalid or missing authentication credentials	Auth headers are missing or incorrect	Check X-Click-Airtime-Email and X-Click-Airtime-Token headers

Transaction Error Messages

The following error messages may be returned by the GET /adp/transactions endpoint:

Message	Description	Resolution
At least one search parameter is required	No query parameters were provided	Include transaction_Id, msisdn, or extRefId in the query string
No transactions found	No transactions match the search criteria	Verify the phone number or external reference ID
Invalid or missing authentication credentials	Auth headers are missing or incorrect	Check X-Click-Airtime-Email and X-Click-Airtime-Token headers

Best Practices

1. Always check the code field — For top-up requests, the code field tells you the specific result. A value of 1 means success; any other value indicates a specific error.

2. Handle timeouts gracefully — If you receive a timeout error on a top-up request, query GET /adp/transactions?extRefId=YOUR_REF before retrying to avoid duplicate transactions.

3. Use unique extRefId values — Generate a unique reference for every transaction attempt. This prevents duplicate deliveries if your retry logic is triggered.

4. Implement exponential backoff — When you receive a 503 response, wait progressively longer between retries (e.g., 1s, 2s, 4s, 8s).

5. Log all responses — Store the full response body for every API call to assist with debugging and reconciliation.