Errors & statuses

How the API reports failures and how to interpret transaction status.

Error response shape

Failed API calls typically return JSON like:

{ "status": false, "message": "…" }

Common HTTP codes

Parameter	Type	Description
`200`	OK	Request succeeded (check status / data).
`400`	Bad Request	Invalid input (e.g. amount below 0.01 or above 100,000).
`401`	Unauthorized	Missing or invalid secret key.
`402`	Payment Required	SMS only — insufficient credits. Buy more under Dashboard → SMS → Credits.
`404`	Not Found	Transaction or SMS message not found for your merchant.
`500`	Server Error	Unexpected failure — retry with backoff.
`503`	Unavailable	SMS sender temporarily unavailable.

Transaction statuses

Parameter	Type	Description
`pending`	status	Awaiting Mobile Money payment.
`partial`	status	Some payment received; waiting for the remaining amount.
`paid`	status	Payment confirmed — safe to fulfill.
`expired`	status	TTL elapsed without full payment. Create a new charge to try again.
`cancelled`	status	Charge was cancelled.

SMS message statuses

Parameter	Type	Description
`pending`	status	Accepted; waiting on the phone to send.
`sent`	status	Handed to the network.
`delivered`	status	Delivery report received (when available).
`failed`	status	Could not send — credits refunded when the queue fails.

Look up with GET /api/v1/sms/:id.