Statuses & errors

6.1 Transaction statuses

status	Final?	What to do
PENDING	No	Wait for the callback, or poll the lookup
SUCCESS	Yes	Fulfil the order
FAILED	Yes	Show the failure. The reason is in statusMessage.
anything else	Treat as not final	Keep checking. After your timeout, flag it for manual review. Never assume failure.

Rules that prevent lost or double payments:

• HTTP 200 means accepted, not paid. Every sandbox PIN outcome, including failures, returns 200. The result is in the body.
• Branch on status, not on statusMessage.
• Never resend a charge after a timeout. Look it up with the same clientCorrelator first. A timed-out request may have reached the customer’s phone.
• Save the clientCorrelator before you send the charge, so you can always look it up.

6.2 Error codes

Every error returns a JSON body with statusCode and statusMessage. Log both.

Code	HTTP	Error	Fix	Retry?
E001	400	Missing required field	Send every field in the request body	No
E002	400	Invalid MSISDN format	Use a valid Zimbabwe number, e.g. 263771234567	No
E003	400	Invalid currency	Use USD or ZWG	No
E004	400	Invalid amount	Positive, at most 2 decimal places	No
E005	400	Duplicate correlator	Generate a new unique clientCorrelator	No
E006	401	Invalid credentials	Check the Authorization header	No
E007	403	Sandbox not enabled	Request Sandbox Access, then Save & Activate	No
E008	404	Transaction not found	Check endUserId + clientCorrelator	No
E009	409	Refund not eligible	Only SUCCESS transactions not already refunded	No
E010	422	Insufficient funds	Customer’s balance is too low (sandbox: PIN 1111)	No
E011	422	Barred MSISDN	The number can’t transact	No
E012	422	Refund exceeds original	Refund at most the original amount	No
E013	422	Limit exceeded	Wallet limit reached (sandbox: PIN 9999)	No
E014	500	Internal server error	Retry with exponential backoff; contact support if it persists	Yes
E015	503	Service unavailable	Sandbox maintenance; retry after the window	Yes

Only 500 and 503 are worth retrying. The 4xx errors fail the same way every time. Fix the request, credentials or state first.

The portal doesn’t publish which statusCode value comes with each Exxx code, so match on the HTTP status and statusMessage. An invalid customer PIN (sandbox PIN 2222) has no Exxx code at all. Detect it from statusMessage.

6.3 Rate limit

The API allows 500 requests per minute. The response to exceeding it isn’t documented. Treat a 429 as “back off and retry later”, and don’t poll faster than every 3 seconds.

---

This page is generated from section 6 of the README in README.md. Spotted something wrong? Open an issue.