Error codes

Envelope

Success: { "success": true, "data": { ... } }

Failure: { "success": false, "code": "PROVIDER_REJECTED", "message": "<user-safe>", "errors": { "recipient.id_number": ["..."] } }

message is fixed per code and may be shown verbatim to end users.

Error codes

Code	HTTP	Meaning	Re-submission behaviour
VALIDATION_ERROR	422	Field errors in errors	Fix and resend
METHOD_UNAVAILABLE	422	Method disabled for vendor / not offered by provider	Offer another method
AMOUNT_OUT_OF_RANGE	422	Outside method limits	Adjust amount
AMOUNT_INCREMENT_INVALID	422	Cash-rail amount not a multiple of R10	Round to R10
RECIPIENT_REJECTED	422	ID checksum / FICA data rejected	Correct the recipient
PROVIDER_REJECTED	422	Provider declined; nothing paid; funds released	Terminal for this attempt
REFERENCE_CONFLICT	409	Reference reused with a different payload	Use a new reference
INSUFFICIENT_BALANCE	409	Vendor prefund too low	Retry after top-up
PENDING_CONFIRMATION	409	Submitted, provider outcome unknown (timeout)	Do not resend. Poll GET /payouts/{reference}
PROVIDER_DOWN	503	Provider unreachable; nothing was sent	Retry with the same reference
UNAUTHENTICATED / FORBIDDEN	401 / 403	Token invalid / lacks scope	Ops
NOT_FOUND	404	Unknown reference for this vendor	—
RATE_LIMITED	429	Throttled	Back off

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.