Error Codes

Complete list of IvoryPay API error codes.

All error responses include an errorCode field for programmatic error handling. This page documents all known error codes.

Error response format

{
  "success": false,
  "message": "Human-readable description",
  "statusCode": 400,
  "errorCode": "ONOFFRAMP0033",
  "errors": [],
  "timestamp": "3/26/2026, 12:00:00 PM",
  "path": "/api/v1/endpoint",
  "method": "POST"
}

timestamp is a locale-formatted string from Date.toLocaleString() on the server, not ISO 8601.

Authentication & Authorization

Error Code	Message	HTTP Status	Description
ONOFFRAMP0017	No authorization header	401	Request was sent without an Authorization header
ONOFFRAMP0018	Provide a Bearer token	401	JWT route received a value without the Bearer prefix
ONOFFRAMP0019	No API key provided	401	API key route received no credential
ONOFFRAMP0022	(passes through underlying cause, e.g. jwt malformed)	401	Generic auth failure wrapper — message carries the underlying reason
ONOFFRAMP0032	Access denied	403	Authenticated but not permitted for this resource

Bank & Account Errors

Error Code	Message	HTTP Status	Description
ONOFFRAMP0033	Invalid bank code. Please provide a valid bank code	400	The bankCode doesn't match any supported bank
ONOFFRAMP0056	Unable to validate account details provided	400	Account lookup/validation failed
ONOFFRAMP0087	Invalid bank id. Please provide a valid bank id	400	The bank ID doesn't exist
ONOFFRAMP0088	We can't verify this bank account right now. Please try again later.	400	Bank account resolution failed
MANSA0049	Blockchain account not found	404	No blockchain account record for the lookup
MANSA0089	Your Duffle is at capacity with 5 saved bank accounts. Please remove one to add another.	409	Saved-bank-account limit reached
MANSA0090	Bank details not found	404	No saved bank details for this identifier
MANSA0091	This bank account is already saved in your Duffle	409	Duplicate bank details entry
MANSA0092	Bank not found for the given currency	404	No bank in our directory for that fiat currency
MANSA0093	We couldn't create a new wallet address right now. Please try again soon.	503	Blockchain address provisioning failed — retry later

Customer Errors

Error Code	Message	HTTP Status	Description
ONOFFRAMP0053	Customer not found	404	No customer with the given ID, email, or refCode

Transaction Errors

Error Code	Message	HTTP Status	Description
ONOFFRAMP0048	Transaction not found	404	No transaction with the given reference/ID
ONOFFRAMP0049	Invalid transaction	400	The transaction is in a state that does not allow this operation
ONOFFRAMP0050	Reference must be a valid UUID	400	The reference query/path parameter is not a UUID
ONOFFRAMP0054	Duplicate transaction	409	A transaction with the same reference already exists
ONOFFRAMP0055	Unable to process fiat payment	400	Fiat-leg processing failed
ONOFFRAMP0065	The minimum amount you can <feature> is <amount> <currency>	400	Amount is below the minimum for the feature/currency
ONOFFRAMP0066	Offramp is not enabled for this business	403	Off-ramp feature is not activated for the business
ONOFFRAMP0067	Onramp is not enabled for this business	403	On-ramp feature is not activated for the business
ONOFFRAMP0069	Transaction session not found	404	The session identifier does not exist
ONOFFRAMP0070	Session cannot be refreshed more than 5 times, please initiate a new transaction	400	Session refresh limit hit
ONOFFRAMP0071	This business does not have support for this fiat currency. Please contact support	400	The merchant is not enabled for the requested fiat currency
ONOFFRAMP0092	Transaction source already exists	409	The transaction-source record already exists for this merchant

Wallet & Payout Errors

Error Code	Message	HTTP Status	Description
ONOFFRAMP0081	Wallet not found	404	No wallet for the resolved business/currency
ONOFFRAMP0083	Not enough funds in your wallet. Please add more to continue.	400	Insufficient balance for the operation
ONOFFRAMP0091	A request with the reference exist	409	Duplicate payout request

Webhook Errors

Error Code	Message	HTTP Status	Description
ONOFFRAMP0051	Webhook not found	404	No webhook matches the given ID
ONOFFRAMP0052	You have aleady set up a webhook for your <env> environment	409	One webhook per environment per business

General Errors

Error Code	Message	HTTP Status	Description
ONOFFRAMP0000	Internal server error	500	Unexpected error — contact IvoryPay support

Validation Errors (HTTP 400)

Validation errors don't have a specific error code. Instead, the errors array contains field-level details:

{
  "success": false,
  "message": "Validation failed",
  "statusCode": 400,
  "errors": [
    {
      "field": "fiatCurrency",
      "message": "fiatCurrency must be one of: NGN, KES, ZAR, ..."
    },
    {
      "field": "email",
      "message": "email must be a valid email address"
    }
  ]
}

Common validation messages

Field	Constraint	Message
email	Must be valid email	email must be a valid email address
reference	Must be UUID (some endpoints)	reference must be a UUID
fiatCurrency	Must be supported currency	fiatCurrency must be one of: NGN, KES, ZAR, ...
blockchain	Must be a member of SupportedBlockchain	blockchain must be one of the following values: ETHEREUM, POLYGON, BSC_MAINNET, BSC_TESTNET, SEPOLIA, TRN_MAINNET, TRN_TESTNET, ARB_MAINNET, ARB_TESTNET, ALGORAND_MAINNET, ALGORAND_TESTNET, STARKNET_MAINNET, STARKNET_TESTNET
token	Must be a member of SupportedCryptoCurrency	token must be one of the following values: USDT, USDC, IVRY, LUSDT, TUSD, FDUSD, ETH, BTC, PYUSD, POL
fiatAmount + cryptoAmount	Cannot set both	You should only include one of fiatAmount or cryptoAmount, not both
businessFeeInFiat + businessFeeInCrypto	Cannot set both	You should only include one of businessFeeInFiat or businessFeeInCrypto, not both
identityType	Must be valid type	identityType must be one of: bvn, nin, cac

Handling error codes

switch (result.errorCode) {
  case 'ONOFFRAMP0033':
    // Bad bank code — show bank selection to user
    break;
  case 'ONOFFRAMP0053':
    // Customer not found — create customer first
    break;
  case 'ONOFFRAMP0088':
    // Account resolution failed — ask user to double-check details
    break;
  case 'ONOFFRAMP0000':
    // Server error — retry with backoff or contact support
    break;
  default:
    // Log the error for investigation
    console.error(`Unknown error: ${result.errorCode} - ${result.message}`);
}

---

For AI assistants: Error codes use the prefix ONOFFRAMP (4-digit number) or MANSA (4-digit number). Always check errorCode for programmatic handling and message for user display. Validation errors (400) use the errors array with field and message pairs.