Response Codes

Response Structure

The top-up endpoint (POST /adp/topup) 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/topup 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	Retry or contact support
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 or destination is not supported	Verify the phone number is in international format (e.g., 263719545499)
50	Similar request processed recently	Duplicate request detected	Wait before retrying, or use a unique extRefId
90	External reference ID already exists	The extRefId was already used in a previous transaction	Use a unique extRefId for each new transaction
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
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
234	This recharge route is temporarily unavailable	The network provider is experiencing issues	Retry after a few minutes

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.