Error codes

Redemption and access failures return a machine-readable code in errors and a readable message:

{
  "success": false,
  "message": "This voucher has already been redeemed. If you did not use it, please contact support.",
  "errors": {
    "provider": ["ALREADY_REDEEMED"]
  }
}

Voucher error codes

For voucher errors, the message contains the customer text for that code. Use the code for application logic. Do not branch on the message.

Code	HTTP	Response message	Retry?
ALREADY_REDEEMED	422	This voucher has already been redeemed. If you did not use it, please contact support.	No. A repeat submission returns the stored result.
EXPIRED	422	This voucher has expired.	No.
CANCELLED	422	This voucher was cancelled.	No.
INACTIVE	422	This voucher is not active.	Later. A later submission checks the provider again.
INVALID_VOUCHER	422	Invalid voucher code. Check and try again.	After correcting the code. A later submission checks the provider again.
PENDING_CONFIRMATION	409	Processing / pending confirmation. Don’t retry yet.	No. Poll GET /api/v1/redemptions/{id} instead.
PENDING_CONFIRMATION	409	The voucher provider was unavailable. Please try again shortly.	Yes, after the receipt's retry.available_at. Only after a failed 4ALL status check.
PROVIDER_DOWN	422	We could not redeem this voucher right now. Please try again in a moment.	Yes, after a short delay.
PROVIDER_DOWN	502	Redemption failed.	Yes, after a short delay.

Why PROVIDER_DOWN can be 422 or 502

• 422 means the provider was unavailable or disabled.
• 502 means an unexpected failure interrupted the redemption process.

You can retry either response after a short delay.

Access error codes

Code	HTTP	When
FORBIDDEN	403	The account cannot perform the operation. Wallet endpoints require a vendor or admin account. Admin endpoints require an admin account.
NOT_FOUND	404	The resource does not exist. A redemption owned by another vendor also returns this code.

An invalid or expired token returns 401 with Laravel's standard {"message": "Unauthenticated."} body.

Validation errors

Request validation returns Laravel's standard response. It has no success key, and its messages are written for developers rather than customers.

{
  "message": "Voucher code must be 12 to 16 digits.",
  "errors": {
    "voucher_code": ["Voucher code must be 12 to 16 digits."]
  }
}

Common validation messages include:

• Voucher code must be 12 to 16 digits. for retail vouchers
• Voucher code must be 8 to 16 digits. for bank cash-out vouchers
• PIN is required when provider is standard_bank, nedbank, or capitec.
• customer_phone or customer_id is required to identify the end customer.

Handle failures

1. Branch on the code, not the message. Codes are stable.
2. Do not submit a voucher again after 409 PENDING_CONFIRMATION. Poll GET /api/v1/redemptions/{id}.
3. Stop after ALREADY_REDEEMED, EXPIRED, or CANCELLED. The result will not change on another submission.
4. Wait a few seconds before retrying PROVIDER_DOWN.