Errors

All errors are returned as a JSON body. The type field is the machine-readable enum name, code is the numeric code, and message is the human-readable description.

Response Structures

Standard Error

Returned for most errors — a flat object with no errors array.

{
  "code": 1010,
  "message": "Invalid request.",
  "type": "BAD_REQUEST"
}

Validation Error

Returned when request payload fails validation (INVALID_PAYLOAD). Includes an errors array detailing each offending field.

{
  "code": 1000,
  "message": "Invalid payload. Please check your request.",
  "type": "INVALID_PAYLOAD",
  "errors": [
    {
      "key": "email",
      "reason": "must not be blank"
    }
  ]
}

Action Required Error

Returned when a prerequisite action must be completed before proceeding.

{
  "code": 1035,
  "message": "Please complete the prerequisite actions.",
  "type": "ACTION_REQUIRED",
  "errors": [
    {
      "key": "actionRequired",
      "reason": "<action_type>"
    }
  ]
}

Error Code Reference

Authentication & Session

HTTP	Code	Type	Message
401	1002	UNAUTHENTICATED	You are not authenticated. Please login to continue.
401	1003	TOKEN_EXPIRED	Your access token has expired. Please get a new token.
401	1004	SESSION_EXPIRED	Your session has expired. Please login again.
400	1036	INVALID_TOKEN	Invalid access token provided.

Authorization & Access

HTTP	Code	Type	Message
403	1001	UNAUTHORISED	You do not have permission to access this resource.
403	1006	BAN	Access to this resource is forbidden.
403	1007	IP_NOT_WHITELISTED	Your IP is not whitelisted.
403	1008	NO_PRIVILEGE	Insufficient Privilege.

Rate Limiting

HTTP	Code	Type	Message
429	1005	THROTTLE	Too many requests. Please try again later.
500	1050	TRANSACTION_LOCKED_BY_RULE	Transaction has been locked.

Request Validation

HTTP	Code	Type	Message
422	1000	INVALID_PAYLOAD	Invalid payload. Please check your request.
500	1018	INVALID_HEADERS	Invalid HTTP headers.

Account Status

HTTP	Code	Type	Message
500	1012	ACCOUNT_INACTIVE	Your account status is inactive.
500	1013	ACCOUNT_SUSPENDED	Your account is suspended.

Configuration & Setup

HTTP	Code	Type	Message
500	1009	PARENT_NOT_FOUND	Parent not configured properly. Please contact VaultsPay support.
500	1015	INVALID_CONFIG	Invalid internal configuration.
500	1020	THIRD_PARTY_CONFIG_NOT_FOUND	Third party config not found.

Transaction Errors

HTTP	Code	Type	Message
500	1017	INVALID_TRANSACTION	Invalid transaction. Please contact VaultsPay support.
500	1019	DUPLICATE_TRANX_ID	Duplicate UUID provided.
500	1021	CHARGE_ACCOUNT_MISSING	The charge account is missing.
500	1022	INSUFFICIENT_BALANCE	Insufficient balance.
500	1023	TRANSACTION_TYPE_NOT_FOUND	Transaction type not found.
500	1024	THIRD_PARTY_NOT_FOUND	Third party not found.
500	1025	SENDER_ACCOUNT_NOT_FOUND	Sender account not found.
500	1026	RECEIVER_ACCOUNT_NOT_FOUND	Receiver account not found.
500	1027	TRANSACTION_CURRENCY_NOT_FOUND	Transaction currency not found.
500	1028	CURRENCY_NOT_FOUND	Currency not found.
500	1029	SENDER_RECEIVER_ACCOUNTS_SAME	Both sender and receiver accounts are same.
500	1030	CURRENCY_MISMATCH	Sender and receiver account currencies do not match.
500	1031	DUPLICATE_GATEWAY_REF_ID	Duplicate gateway Ref ID provided.
500	1032	TRANSACTION_REFERENCE_MISSING	Transaction reference ID not provided.
500	1033	FULL_AMOUNT_PAID	Full amount has already been paid.
500	1034	TRANSACTION_PREVENTED_BY_RULE	One of the rules for this transaction has failed.
500	1038	SETTLEMENT_NOT_FOUND	Settlement not found.
500	1039	SETTLEMENT_AMOUNT_NOT_FOUND	Settlement amount not found.
500	1040	TRANSACTION_NOT_FOUND	Transaction not found.
500	1041	CONFIG_ACCOUNT_USER_CONFLICTS	Third party config user and account holder conflicts.
500	1042	INVALID_SETTLEMENT_STATUS	Invalid settlement status.
500	1044	CHARGE_AMOUNT_GREATER_THAN_TRANSACTION	Charge amount is greater than transaction amount.
500	1045	SENDER_ACCOUNT_INACTIVE	Sender account is not active.
500	1046	RECEIVER_ACCOUNT_INACTIVE	Receiver account is not active.
500	1051	TRANSACTION_PREVENTED_BY_PREVENT_RULE	Transaction prevented due to prevent rule.
500	1052	TRANSACTION_PREVENTED_BY_CHARGE_RULE	Transaction prevented due to charge rule.
500	1053	TRANSACTION_PREVENTED_BY_FRAUD_RULE	Transaction prevented due to fraud rule.
500	1054	TRANSACTION_PREVENTED_BY_LIMIT_RULE	Transaction prevented due to limit rule.
500	1055	TRANSACTION_PREVENTED_BY_USER_SECURITY_RULE	Transaction prevented due to security rule.
500	1055	TRANSACTION_PREVENTED_BY_KYC_RULE	Transaction prevented due to user’s KYC status.
500	1064	THIRD_PARTY_TRANSACTION_FAILURE	Transaction failed at third party.
500	1069	TRANSACTION_ALREADY_REVERSED	Transaction already reversed.
500	1070	SENDER_ACCOUNT_NOT_FOUND_ON_THIRDPARTY	Sender account does not exist on the third party.
500	1071	RECEIVER_ACCOUNT_NOT_FOUND_ON_THIRDPARTY	Receiver account does not exist on the third party.

Resource Not Found

HTTP	Code	Type	Message
404	1047	NOT_FOUND	Request resource not found.
500	1056	NO_RULES_FOUND	No rules found.
500	1057	USER_NOT_FOUND	User not found.
500	1058	PHONE_NOT_FOUND	Phone not found.
500	1059	EMAIL_NOT_FOUND	Email not found.
500	1060	USER_NAME_NOT_FOUND	Username not found.
500	1061	ACCOUNT_NOT_FOUND	Account not found.
500	1062	ACCOUNT_NOT_FOUND_AT_THIRDPARTY	Account not found at third party.
500	1065	ADDRESS_NOT_FOUND	The address fields are required.

Card Errors

HTTP	Code	Type	Message
500	1043	INVALID_TOKEN_OR_CARD_ID	Invalid card ID or token provided.
500	1063	CARD_EXPIRED	Card expired.
500	1067	CARD_CREATION_FAILED	Card request is malformed, please check the request and try again.

Verification & Security

HTTP	Code	Type	Message
500	1014	OTP_REQUIRED	OTP verification is required.
500	1035	ACTION_REQUIRED	Please complete the prerequisite actions.
500	1037	RECAPTCHA_REQUIRED	reCAPTCHA verification is required.
500	1048	RECAPTCHA_SCORE_TOO_LOW	reCAPTCHA score too low.
422	1049	DECRYPTION_FAILED	Error while decrypting request.

Smart Auth

HTTP	Code	Type	Message
404	1080	SMART_AUTH_REQUEST_NOT_FOUND	Smart Auth request not found.
410	1081	SMART_AUTH_REQUEST_EXPIRED	Smart Auth request has expired.
409	1082	SMART_AUTH_INVALID_STATE	Smart Auth request is in an invalid state for this operation.
429	1083	SMART_AUTH_MAX_ATTEMPTS	Maximum verification attempts exceeded.
400	1084	SMART_AUTH_INVALID_TOKEN	Invalid or expired challenge token.
422	1085	SMART_AUTH_VERIFICATION_FAILED	Smart Auth verification failed.
423	1086	SMART_AUTH_ACCOUNT_LOCKED	Account locked due to too many failed verification attempts.
429	1087	SMART_AUTH_RATE_LIMITED	Too many pending Smart Auth requests. Please try again later.
409	1088	SMART_AUTH_TAMPER_DETECTED	Action payload fingerprint mismatch.
400	1089	SMART_AUTH_ACTION_NOT_CONFIGURED	Smart Auth action type is not configured or disabled.
400	1090	SMART_AUTH_UNSUPPORTED_METHOD	Verification method is not supported.
502	1091	SMART_AUTH_CALLBACK_FAILED	External provider callback failed.
422	1092	SMART_AUTH_BIOMETRIC_UNAVAILABLE	Biometric verification is not available for this device.
422	1093	SMART_AUTH_PASSCODE_NOT_SET	Passcode is not configured for this user.
409	1094	SMART_AUTH_ALREADY_CONSUMED	Smart Auth request has already been consumed and cannot be reused.
422	1095	SMART_AUTH_INVALID_PASSCODE	Invalid passcode provided.

Passcode & Device

HTTP	Code	Type	Message
403	1096	PASSCODE_REQUIRED	Passcode verification is required.
401	1097	INVALID_PASSCODE	Invalid passcode provided.
423	1098	PASSCODE_LOCKED	Too many failed passcode attempts. Please try again later.
422	1099	PASSCODE_NOT_SET	Passcode is not configured. Please set your passcode first.
403	1100	CONTACT_SUPPORT_FOR_RESET	Please contact support to reset your credentials.
403	1101	DEVICE_LIMIT_EXCEEDED	Maximum device limit reached. Please remove a device or contact admin.
202	1102	DEVICE_SWITCH_PENDING	Login approval is pending on your other device.
403	1103	DEVICE_SWITCH_DECLINED	Login request was declined from the other device.
410	1104	MAGIC_LINK_EXPIRED	This magic link has expired or is invalid.
409	1105	MAGIC_LINK_ALREADY_USED	This magic link has already been used.

System Errors

HTTP	Code	Type	Message
500	1010	BAD_REQUEST	Invalid request.
500	1011	INTERNAL_ERROR	Something unexpected went wrong. Please contact VaultsPay support.
503	1016	SERVICE_DOWN	The service is currently not available at the moment.
504	1066	GATEWAY_TIMEOUT	Gateway timeout.
500	1068	DATA_ELELEMT_PARSING	An error occured in parsing FAST data element.
500	1047	INVALID_BASIC_AUTH	Invalid Basic Auth Credentials.
500	9999	UNKNOWN_ERROR	Unknown error. Please try again later.

Default HTTP status: Any error code not listed in the HTTP mappings above defaults to 500 Internal Server Error.

Transfer Webhooks API Reference