Error codes

Envelope

Success: { "success": true, "data": { ... } }. Methods use an array in data; a successful SMS resend uses null.

Failure: { "success": false, "code": "VALIDATION_ERROR", "message": "<fixed message>", "errors": { "recipient.id_number": ["..."] } }.

message is fixed per code and may be shown to end users. Branch on code. errors is an object, empty when there are no field errors. Batch validation keys include the item index, for example payouts.0.recipient.phone.

Error codes

Code	HTTP	Meaning	Re-submission behaviour
VALIDATION_ERROR	422	Invalid request fields	Correct the reported fields
METHOD_UNAVAILABLE	422	Method disabled, unsupported or unavailable for this operation	Check /methods and the existing payout before changing method
AMOUNT_OUT_OF_RANGE	422	Outside method limits or vendor daily cap	Check limits and the requested amount
AMOUNT_INCREMENT_INVALID	422	Cash amount is not a multiple of R10	Correct the amount with the customer
RECIPIENT_REJECTED	422	Recipient data rejected	Correct the recipient data
PROVIDER_REJECTED	422	Definitive rejection; gateway reservation released	Terminal for the stored payout; reconcile before a separate attempt
REFERENCE_CONFLICT	409	Reference reused with different details	Retrieve the original; use a new reference only for a separate payment
INSUFFICIENT_BALANCE	409	Insufficient gateway prefund for amount plus fee	Top up, then retry the same request
PENDING_CONFIRMATION	409	Outcome unconfirmed, or requested operation needs a paid payout	Keep the hold and poll the original reference
PROVIDER_DOWN	503	Execution paused or submission preflight unavailable	Read the original reference; retry the same body and reference
UNAUTHENTICATED / FORBIDDEN	401 / 403	Invalid token or inactive vendor / insufficient scope or dispatch permission	Check credentials and vendor access
NOT_FOUND	404	Unknown reference for this vendor	Verify the vendor and original reference
RATE_LIMITED	429	Request throttle or SMS resend limit	Back off; SMS also has a lifetime attempt cap

An error response alone does not prove that no payout record or reservation exists. PROVIDER_DOWN can leave an unattempted payout reserved for later processing. A connection failure can hide a successful submission. Read the original reference, preserve the customer hold while unresolved, and never create a replacement payment just to bypass an error. If a record is absent, retry with the same body and reference after resolving the reported problem.

The fixed messages are listed below.

Fixed messages

Use code in application logic. The message below is fixed for that code and may be shown to the end user. Validation details appear in errors.

Code	HTTP	Message
VALIDATION_ERROR	422	Some payout details are missing or invalid.
METHOD_UNAVAILABLE	422	This payout method is not available right now.
AMOUNT_OUT_OF_RANGE	422	The amount is outside the limits for this payout method.
AMOUNT_INCREMENT_INVALID	422	Cash payouts must be in multiples of R10 — ATMs cannot pay out other amounts.
RECIPIENT_REJECTED	422	The recipient details were not accepted. Check the ID number and phone number.
REFERENCE_CONFLICT	409	This payout reference has already been used with different details.
INSUFFICIENT_BALANCE	409	Payouts are temporarily unavailable. Please try again later.
PENDING_CONFIRMATION	409	Your payout is being processed. You will be notified once it is complete.
PROVIDER_REJECTED	422	The payout was declined by the payment provider.
PROVIDER_DOWN	503	We could not process the payout right now. Please try again in a moment.
UNAUTHENTICATED	401	Payouts are not available for this account.
FORBIDDEN	403	Payouts are not available for this account.
NOT_FOUND	404	Payout not found.
RATE_LIMITED	429	Too many requests. Please wait a moment and try again.