Error Codes

Use this reference to identify the error code, where it appears in the response envelope, and the expected HTTP status.

Legend (envelope): rest → code appears at the top level of the error response; validation details → code appears inside a details array (HTTP status as listed); basicAuth → flat { message, code }; success data → code returned in a success payload; webhook/catalog → emitted in webhooks or order failure fields, not as REST errors.

Authentication Errors

Error Code	Endpoint	HTTP Status	Envelope	Description
`CUSTOMER_NOT_FOUND`	All	404	basicAuth	The username and password used for authentication could not be found in the system.
`UNAUTHORIZED_CUSTOMER`	All	401	basicAuth	The MID header is either empty or could not be found in the system.

Request Validation Errors

Error Code	Endpoint	HTTP Status	Envelope	Description
`INVALID_ARGUMENTS`	All	400	validation details	Invalid arguments provided in the request.
`MISSING_ARGUMENTS`	All	400	validation details	Required arguments are missing from the request.
`NOT_FOUND`	All	404	rest	Data not found.
`VALIDATION_ERROR`	All	400	rest (catalog codes may appear in details)	Request validation failed (e.g., missing API keys, authorization header, or invalid parameters).
`CRYPTO_CURRENCY_NOT_FOUND`	All	404	validation details	Crypto currency not found.
`CRYPTO_NETWORK_NOT_FOUND`	All	404	validation details	Crypto network not found.
`CRYPTO_TICKER_NOT_FOUND`	All	404	validation details	Crypto ticker not found.

Rate & Quote Errors

Error Code	Endpoint	HTTP Status	Envelope	Description
`CURRENCY_NOT_FOUND`	All	400	rest	The requested currency is not supported or not found.
`QUOTES_LIMIT_ERROR`	Exchange Rates, Order	400	rest	The provided amount is not in the limits for selected trading pair.
`QUOTES_EXPIRED`	Exchange Rates, Order	400	rest	The provided quotes have expired and are no longer valid.

User Errors

Error Code	Endpoint	HTTP Status	Envelope	Description
`CONFLICT`	User	409	—	The user already exists in the system.
`USER_NOT_FOUND`	User	404 (rest); 400 (nested)	rest or validation details	The specified user could not be found in the system.
`AGE_LIMIT_ERROR`	User	400	rest	The user's age is outside the allowed limits.
`USER_ALREADY_EXISTS`	User	201 (success payload)	success data	User already exists with the provided email or phone.
`USER_ALREADY_EXISTS_AS_BUSINESS`	User	400	rest	Individual user creation failed because user already exists as a business.
`USER_ALREADY_EXISTS_AS_INDIVIDUAL`	User	400	rest	Business user creation failed because user already exists as an individual.
`USER_CREATION_ERROR`	User	400	rest	Failed to create user (individual or business).
`USER_ORGANIZATION_MISMATCH`	All	400	rest or validation details	User does not belong to the organization.
`USER_TYPE_MISMATCH`	KYC / KYB	400	validation details	User is not an individual user.
`USER_NOT_AN_INDIVIDUAL`	KYC / KYB	400	rest or validation details	User is not an individual.
`USER_NOT_A_BUSINESS`	KYC / KYB	400	rest	User is not a business.

KYC / KYB Errors

Error Code	Endpoint	HTTP Status	Envelope	Description
`INVALID_TOKEN	KYC - Same vendor	422	rest	Invalid share token
`INVALID_TOKEN_DETAILS`	KYC - Same vendor	422	rest	User email or phone does not match with share token email or phone.
`TOKEN_DATA_INCOMPLETE`	KYC - Same vendor	422	rest	Required KYC information is missing in the share token response.
`KYC_IMPORT_FAILED`	KYC - Same vendor	400	rest	Invalid token format.
`KYB_LINK_GENERATION_FAILED`	KYB	400	rest	KYB simplified level verification has already been initiated.
`BASIC_KYC_NOT_APPROVED`	KYC	400	validation details	User has not completed basic KYC.
`STANDARD_KYC_NOT_APPROVED`	KYC	400	validation details	User has not completed standard KYC.
`KYC_ALREADY_SUBMITTED`	KYC	400	validation details	User has already submitted the KYC (standard or advanced).
`USER_BLOCKED_OR_REJECTED`	KYC / KYB, Order	400	rest or validation details	User is blocked or rejected.
`INVALID_COUNTRY_CODE`	KYC / KYB	400	rest	Invalid country code.
`INVALID_ID_DOC_ISSUER_COUNTRY_CODE`	KYC / KYB	400	rest	Invalid ID document issuer country code.
`INVALID_NATIONALITY_CODE`	KYC / KYB	400	rest	Invalid nationality code.
`COUNTRY_NOT_SUPPORTED`	KYC / KYB	400	rest	Country is not supported.
`ID_DOC_ISSUER_COUNTRY_NOT_SUPPORTED`	KYC / KYB	400	rest	ID document issuer country is not supported.
`NATIONALITY_NOT_SUPPORTED`	KYC / KYB	400	rest	Nationality is not supported.
`INVALID_ID_DOC_TYPE`	KYC / KYB	400	rest	Invalid ID document type.
`BASIC_KYB_NOT_APPROVED`	KYB	400	rest	User has not completed basic KYB.
`STANDARD_KYB_NOT_APPROVED`	KYB	400	rest	User has not completed standard KYB.
`STANDARD_KYB_ALREADY_APPROVED`	KYB	400	rest	User has already completed standard KYB.
`ADVANCED_KYB_ALREADY_APPROVED`	KYB	400	rest	User has already completed advanced KYB.

Invoice Errors

Error Code	Endpoint	HTTP Status	Envelope	Description
`FILE_REQUIRED`	Order	400	validation details	An invoice is required to perform the transaction.
`INVALID_FILE_TYPE`	All	400	validation details	Uploaded invoice file type is invalid.
`FILE_TOO_LARGE`	All	400	validation details	Uploaded invoice file exceeds allowed size.
`INVOICE_ID_REQUIRED`	Order	400	validation details	Invoice ID is required.
`INVOICE_NOT_FOUND`	Order	404 (invoice GET); 400 nested	rest or validation details	Invoice not found for the provided ID.
`INVOICE_USER_ID_MISMATCH`	Order	400	validation details	Invoice user ID does not match the request user.
`INVALID_INVOICE_TYPE`	Order	400	validation details	Invoice type is invalid for the requested flow.
`INVOICE_ALREADY_PROCESSED`	Order	400	validation details	Invoice has already been processed.

Transfer / Order Errors

Error Code	Endpoint	HTTP Status	Envelope	Description
`INSUFFICIENT_BALANCE`	Order	400	validation details	The account has insufficient balance to complete the transaction.
`RESTRICTED_ACCESS`	Order	400	rest	The user is not allowed to do transaction.
`INVALID_ORDER_TYPE`	Order	400	validation details	Order type is invalid for the requested flow.
`INVALID_SETTLEMENT_TYPE`	Order	400	validation details	Settlement type is not allowed for the flow.
`USER_ID_REQUIRED`	Order	400	validation details	User ID is required for the transfer.
`DESTINATION_USER_NOT_FOUND`	Order	400	validation details	Destination user not found.
`RECIPIENT_USER_NOT_FOUND`	Order	400	validation details	Recipient user not found.
`COUNTRY_NOT_ALLOWED`	Order	400	validation details	User or organization country is not allowed for the flow.
`QUOTE_INSUFFICIENT_ORDER_AMOUNT`	Order	400	validation details (rest in simulations)	Quote/order amount is below the minimum required.
`AMOUNT_VALIDATION_FAILED`	Order	400	validation details	Amount validation failed for the transfer.
`SOURCE_AMOUNT_VALIDATION_FAILED`	Order	400	validation details	Source amount validation failed for the transfer.
`DESTINATION_AMOUNT_VALIDATION_FAILED`	Order	400	validation details	Destination amount validation failed for the transfer.
`SOURCE_AMOUNT_REQUIRED`	Order	400	validation details	Source amount is required.
`WALLET_CREATION_ERROR`	Order	400	validation details	Failed to create or fetch wallet for the transfer.
`WALLET_ADDRESS_REQUIRED`	Order	400	validation details	Wallet address is required for the flow.
`WALLET_ADDRESS_INVALID`	Order	400	validation details	Wallet address failed validation.
`SENDERS_WALLET_ADDRESS_INVALID`	Order	400	validation details	Sender's wallet address failed validation.
`INVALID_DESTINATION_CURRENCY`	Order	400	validation details	Destination currency is invalid for the flow.
`PAYMENT_CODE_AND_PAYMENT_TYPE_REQUIRED`	Order	400	validation details	Payment code and payment type are required for the transfer.
`PAYMENT_TYPE_REQUIRED`	Order	400	validation details	Payment type is required.
`PAYMENT_CODE_REQUIRED`	Order	400	validation details	Payment code is required.
`PAYMENT_TYPE_MISMATCH`	Order	400	validation details	Payment type does not match the expected value.
`PAYMENT_METHOD_NOT_FOUND`	Order	404 (Rest); 400 (nested)	rest or validation details	Payment method not found for the given payment code/type.
`SOURCE_PAYMENT_METHOD_NOT_FOUND`	Order	400	validation details	Source payment method not found.
`DESTINATION_PAYMENT_METHOD_NOT_FOUND`	Order	400	validation details	Destination payment method not found.
`SOURCE_PAYMENT_TYPE_REQUIRED`	Order	400	validation details	Source payment type is required.
`SOURCE_PAYMENT_CODE_REQUIRED`	Order	400	validation details	Source payment code is required.
`DESTINATION_PAYMENT_TYPE_REQUIRED`	Order	400	validation details	Destination payment type is required.
`DESTINATION_PAYMENT_CODE_REQUIRED`	Order	400	validation details	Destination payment code is required.
`SUCCESS_REDIRECT_URL_REQUIRED`	Order	400	validation details	Success redirect URL is required.
`FAILURE_REDIRECT_URL_REQUIRED`	Order	400	validation details	Failure redirect URL is required.
`DEVICE_DETAILS_REQUIRED`	Order	400	validation details	Device details are required (e.g., for card/headless flows).

Compliance Errors

Error Code	Endpoint	HTTP Status	Envelope	Description
`EMAIL_VERIFICATION_FAILED`	User, Order	400	validation details	Email verification failed and cannot be used for contact creation. Please contact support for further assistance
`EMAIL_UNDER_MANUAL_REVIEW`	User, Order	400	validation details	Email is under manual review. Please wait 24-48 hours or contact support.
`EMAIL_NOT_ALLOWED`	User, Order	409	rest	Email not allowed for the user (compliance check failed).
`DEVICE_UNDER_MANUAL_REVIEW`	Order	400	validation details	Account is under manual review due to a device & biometric risk check. Please wait 24-48 hours or contact support.
`DEVICE_VERIFICATION_FAILED`	Order	400	validation details	Account is disabled because the device & biometric check failed. Please contact support for further assistance.
`KYT_UNUSUAL_BEHAVIOUR_MANUAL_REVIEW`	Order	400	validation details	Account is under manual review because the system flagged unusual transaction behavior. Please wait 24-48 hours for a final outcome or contact support.
`KYT_VELOCITY_RISK_TEMP_BLOCK`	Order	400	validation details	Account is temporarily disabled for 24 hours due to unusual transaction behavior. Please retry after 24 hours or contact support.
`KYT_UNUSUAL_BEHAVIOUR_PERM_BLOCK`	Order	400	validation details	Account is permanently disabled due to unusual transaction behavior. Please contact support to reinstate this account.
`KYT_CHECK_FAILED`	Order	400	validation details	KYT check failed.
`STANDARD_KYC_REQUIRED`	Order	400	validation details	Limit breached – Standard KYC is required.
`ENHANCED_KYC_REQUIRED`	Order	400	validation details	Limit breached – Enhanced KYC is required.
`BASIC_SCREENING_IN_PROGRESS`	Order	400	validation details	User creation is in progress. User's Basic KYC is pending.
`BASIC_SCREENING_REJECTED`	Order	400	validation details	User KYC has been rejected.
`KYC_EXPIRED`	Order	400	validation details	User KYC document has expired.
`KYC_PENDING`	Order	400	validation details	User KYC is pending; transfer cannot proceed.
`KYC_REJECTED`	Order	400	validation details	KYC was rejected.
`KYC_MANUAL_REVIEW`	Order	400	validation details	KYC is under manual review.
`RESUBMISSION_REQUIRED`	Order	400	validation details	User KYC failed – Please resubmit your KYC.
`MAXIMUM_LIMIT_BREACHED`	Order	400	validation details	Maximum transaction limit reached. No further orders will be accepted for this user.
`KYB_REJECTED`	Order	400	validation details	KYB was rejected.
`KYB_EXPIRED`	KYC / KYB	400	validation details	KYB has expired.
`KYB_MANUAL_REVIEW`	Order	400	validation details	KYB is under manual review.
`KYB_PENDING`	Order	400	validation details	KYB is pending.
`STANDARD_KYB_REQUIRED`	Order	400	validation details	Standard KYB level is required.
`ENHANCED_KYB_REQUIRED`	Order	400	validation details	Enhanced KYB level is required.
`CUSTOMER_RISK_MATRIX_CHECK_FAILED`	Order	400	validation details	Customer risk matrix check failed.

Internal Errors

Error Code	Endpoint	HTTP Status	Envelope	Description
`INTERNAL_SERVER_ERROR`	System	500	rest	An internal server error occurred while processing the request.

Webhook Errors

Error Code	Error Type	Description
`PAYMENT_NOT_COMPLETED`	Order	User has cancelled the payment or didn't complete within the session.
`NAME_NOT_MATCHED`	Compliance	User name on the sender's bank account detail didn't match with TransFi.
`USER_CONSENT_NOT_PROVIDED`	Compliance	User didn't give gaming order consent within the defined time.
`BEHAVIORAL_CHECK_IN_REVIEW`	Compliance	Biometric check of the user's device is under review.
`BEHAVIORAL_CHECK_FAILED`	Compliance	Biometric check of the user's device has failed.
`AMOUNT_MISMATCH`	Order	The payment amount does not match the expected amount.
`AUTHENTICATION_FAILED`	Order	User authentication failed.
`BANK_ACCOUNT_ALREADY_IN_USE`	Order	This bank account is already linked to another user.
`BANK_UNDER_MAINTENANCE`	Order	There was a technical issue with the bank.
`DECLINED_BY_BANK`	Order	Bank has declined this transaction.
`INVALID_ACCOUNT_DETAILS`	Order	The provided account details are invalid.
`TRANSACTION_EXPIRED`	Order	Payment is not completed within the time.
`VALIDATION_FAILED`	Order	Validation has failed for the transaction.
`TRANSACTION_FAILED`	Order	Transaction has failed.
`OTHERS`	Any	An unexpected error occurred.