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": "2026-03-26T12:00:00.000Z",
  "path": "/api/v1/endpoint",
  "method": "POST"
}

Bank & Account Errors

Error Code	Message	HTTP Status	Description
ONOFFRAMP0033	Invalid bank code	400	The bankCode doesn't match any supported bank
ONOFFRAMP0087	Invalid bank ID	400	The bank ID doesn't exist
ONOFFRAMP0056	Unable to validate account details	400	Account lookup/validation failed
ONOFFRAMP0088	Unable to resolve bank account	400	Bank account resolution failed
MANSA0090	Bank details not found	404	No saved bank details for this identifier
MANSA0091	Bank details already saved	409	Duplicate bank details entry
MANSA0092	Bank not found in currency	404	No bank available for the specified currency

Customer Errors

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

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, GHS, 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, GHS, ...
blockchain	Must be supported chain	blockchain must be one of: BSC_MAINNET, ETHEREUM, ...
token	Must be supported token	token must be one of: USDT, USDC, ETH, ...
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.