Errors

Overview

The Cashless API uses standard HTTP status codes to indicate success or failure. For client-side (4xx) and server-side (5xx) errors, the response body contains a JSON object with a specific errorCode and descriptive message.

{
  "success": false,
  "message": "External reference already in use.",
  "errorCode": "DUPLICATE_EXTERNAL_REFERENCE"
}

Common Errors

HTTP Status	Error Code	Description
403 Forbidden	`USER_NOT_ONBOARDED`	Account has not completed the required onboarding process.
409 Conflict	`DUPLICATE_EXTERNAL_REFERENCE`	The `externalReference` has already been used — must be unique.
422 Unprocessable Entity	`INSUFFICIENT_FUNDS`	Wallet balance is too low to complete the debit transaction.
503 Service Unavailable	`FX_RATE_UNAVAILABLE`	Temporarily unable to retrieve a currency conversion rate. Safe to retry.
500 Internal Server Error	`INTERNAL_SERVER_ERROR`	Unexpected error on our end. Report if it persists.

Payout Specific Errors

HTTP Status	Error Code	Description
403 Forbidden	`CURRENCY_NOT_ENABLED`	Currency not enabled for payouts on this account.
404 Not Found	`PAYOUT_PROVIDER_NOT_FOUND`	No payment provider found for the specified currency and destination.
422 Unprocessable Entity	`DEBIT_CURRENCY_NOT_SUPPORTED`	The combination of `debitCurrency` and `currency` is not allowed.
422 Unprocessable Entity	`MOMO_CODE_REQUIRED`	`payoutMethod.code` (operator code) is required for MoMo payouts in this region.

Collections Specific Errors

HTTP Status	Error Code	Description
403 Forbidden	`CURRENCY_NOT_ENABLED`	Currency not enabled for collections on this account.
422 Unprocessable Entity	`UNSUPPORTED_CURRENCY`	Currency is not supported for collections.
422 Unprocessable Entity	`MOMO_CODE_REQUIRED`	Charge method does not support the selected currency.
422 Unprocessable Entity	`WALLET_CURRENCY_NOT_SUPPORTED`	Cross-currency deposit combination not supported.
400 Bad Request	`MOMO_OPERATOR_ID_REQUIRED`	Selected provider requires a `momoOperatorId`.
404 Not Found	`PROVIDER_NOT_FOUND`	No collection provider matches the currency/method/operator/country/amount.
404 Not Found	`COUNTRY_CODE_NOT_FOUND`	Phone number prefix doesn't match a supported XOF country.