Error Codes Reference

Response Structure

All API responses follow a consistent JSON structure that includes status information and error details when applicable.

1

Important Note

• Always check the success field before processing the response

• Purpose of the code field to categorize errors displayed

• Purpose of info field is to add human-readable error descriptions

Success Response Example

Copy

{
   "success": true,
   "status": 201,
   "message": "Created",
   "code": "EN-SUCCESS-001",
   "info": "User created successfully",
   "data": {
       "_id": "690c69f046492638edxxxxxx",
       "ref_partnerId": "800005b1-5d7a-46ca-8bc7-3a33028312f9",
       "ref_partnerObjectID": "63c607a8c789807740a85870",
       "email": "[email protected]",
       "tac_agreed": false,
       "kyc_Status": false,
       "kyc_Status_Detail": false,
       "allow_whitelisting_addresses": true,
       "is_locked_to_transactions": false,
       "whitelisted_wallets_list": [],
       "whitelisted_bankAccount_list": [],
       "whitelisted_mobileWallet_list": [],
       "external_sumsub_ID": "bdf0a02b-b0f3-45a0-8599-4fbcd1506d56",
       "createdAt": "2025-11-06T09:27:12.413Z",
       "updatedAt": "2025-11-06T09:27:12.413Z"
   }
}

Error Response Example

Copy

{
   "success": false,
   "status": 400,
   "message": "Bad Request",
   "code": "EN-DATA-009",
   "info": "email must be an email"
}

Response Fields

Field	Type	Description
success	boolean	Indicates whether the request was successful
status	integer	HTTP status code
message	string	HTTP status message
code	string	Specific error or success code for programmatic handling
info	string	Human-readable description with additional context
data	object	Response payload (only present in successful responses)

---

Success Code

Code	Status	Message	Description
EN-SUCCESS-001	200	OK	Request completed successfully
EN-SUCCESS-001	201	Created	Quote created sucesfully

---

Error Code Categories

Authentication Errors (EN-AUTH-xxx)

Authentication-related errors occur when credentials are invalid or authorization fails.

Code	Status	Message	Description
EN-AUTH-001	401	Unauthorized	Invalid credentials
EN-AUTH-002	401	Unauthorized	Authentication error
EN-AUTH-004	403	Forbidden	{requestEmail} is not authorized to access unregistered API services
EN-AUTH-005	401	Unauthorized	Invalid connection token provided

Resolution Steps:

• Verify your API credentials are correct

• Check that your authentication token hasn't expired

• Ensure you have proper authorization for the requested resource

• Contact support if you need access to additional API services

---

Business Logic Errors (EN-BUS-xxx)

Business rule violations and operational constraints.

Code	Status	Message	Description
EN-BUS-001	503	Service Unavailable	Transaction not processed. Please contact operations
EN-BUS-002	404	Not Found	No document found – mandatory for China
EN-BUS-003	400	Bad Request	Bank {bankName} is not supported by local provider. Please contact operations
EN-BUS-004	404	Not Found	beneficiaryBankName '{bankName}' is not found, please contact operations
EN-BUS-005	409	Conflict	bankName already exists
EN-BUS-006	400	Bad Request	The specified provider is not active or valid for the selected country, please verify the provider/country/mobile or contact operations

Resolution Steps:

• Verify the bank or provider is supported in the target country

• Ensure all required documents are provided for country-specific requirements

• Contact operations for provider activation or support

---

Data Errors (EN-DATA-xxx)

Missing or incorrect data in the request.

Code	Status	Message	Description
EN-DATA-001	400	Bad Request	User first name is required
EN-DATA-002	400	Bad Request	User last name is required
EN-DATA-003	400	Bad Request	User address is required
EN-DATA-004	400	Bad Request	Currency Code is missing
EN-DATA-005	400	Bad Request	msisdn / sender_msisdn / receiver_msisdn can not be empty
EN-DATA-006	400	Bad Request	Missing Bank Identifier - bankcode (BIC, routing number, sort code) or banksubcode (e.g. IFSC, branch code)
EN-DATA-007	404	Not Found	No user found with email {requestEmail}
EN-DATA-008	500	Internal Server Error	Failed to fetch payment provider fees or limits for the country
EN-DATA-009	400	Bad Request	Some required fields are missing or invalid
EN-DATA-010	404	Not Found	KYC details not found for partner user {userEmail}
EN-DATA-011	404	Not Found	No whitelisted bank accounts were found for the account: {requestEmail}
EN-DATA-012	400	Bad Request	Please specify the PIX method in the provider field
EN-DATA-013	404	Not Found	{partnerEmail} is not a registered entity
EN-DATA-014	403	Forbidden	Something went wrong. Please contact operations
EN-DATA-015	404	Not Found	Not Found, please contact operations
EN-DATA-016	500	Internal Server Error	Something went wrong. Please contact operations
EN-DATA-017	400	Bad Request	Please specify the PIX method in the provider field
EN-DATA-023	404	Not Found	Transaction not found for the provided order ID
EN-DATA-036	404	Not Found	No wallet provider found for {countryCode}

Resolution Steps:

• Ensure all required fields are included in your request

• Verify user accounts exist before attempting operations

• Complete KYC verification before initiating transactions

• Whitelist bank accounts or wallets before use

---

State Errors (EN-STATE-xxx)

Account or transaction state issues.

Code	Status	Message	Description
EN-STATE-001	423	Locked	User account is locked, please contact support
EN-STATE-002	404	Not Found	Quote ID has expired or a transaction has already been initiated for this Quote ID
EN-STATE-003	423	Locked	Account is temporarily locked while a transaction is pending settlement
EN-STATE-004	400	Bad Request	Onboarding failed. Please try again later or contact operations
EN-STATE-005	403	Forbidden	{email} account is disabled, please contact super admin

Resolution Steps:

• Contact support to unlock your account

• Generate a new quote if the previous one has expired

• Wait for pending transactions to settle before initiating new ones

• Contact your administrator for account reactivation

---

System Errors (EN-SYS-xxx)

Internal system errors.

Code	Status	Message	Description
EN-SYS-001	500	Internal Server Error	System error occurred
EN-SYS-002	503	Service Unavailable	Service temporarily unavailable

Resolution Steps:

• Retry your request after a brief delay

• If the issue persists, contact technical support

---

Unknown Errors (EN-UNK-xxx)

Unexpected errors that require operational support.

Code	Status	Message	Description
EN-UNK-003	500	Internal Server Error	Something went wrong. Please contact operations
EN-UNK-005	500	Internal Server Error	User creation failed. Please try again later or contact operations
EN-UNK-006	500	Internal Server Error	Something went wrong. Please contact operations
EN-UNK-007	500	Internal Server Error	Something went wrong. Please contact operations

Resolution Steps:

• Retry your request

• Contact operations if the error persists

---

Unsupported Feature Errors (EN-UNS-xxx)

Features that are not available or supported.

Code	Status	Message	Description
EN-UNS-001	403	Forbidden	Feature disabled: Whitelisting can only be done manually, not via API. Please contact operations for further information
EN-UNS-003	400	Bad Request	Country not supported by vendor. Please contact operations

Resolution Steps:

• Contact operations for manual whitelisting

• Verify country support before initiating transactions

---

Validation Errors (EN-VAL-xxx)

Input validation failures.

Code	Status	Message	Description
EN-VAL-001	400	Bad Request	Validation error
EN-VAL-002	400	Bad Request	User date of birth must be greater than 18 years
EN-VAL-005	400	Bad Request	Validation error
EN-VAL-006	400	Bad Request	Validation error
EN-VAL-007	400	Bad Request	Validation error
EN-VAL-008	400	Bad Request	Validation error
EN-VAL-009	400	Bad Request	Validation error
EN-VAL-010	400	Bad Request	Validation error
EN-VAL-011	400	Bad Request	Validation error
EN-VAL-012	400	Bad Request	Validation error
EN-VAL-013	400	Bad Request	Validation error
EN-VAL-014	404	Not Found	Country has incorrect format or not supported, please contact operations
EN-VAL-015	400	Bad Request	Country is missing or in incorrect format
EN-VAL-016	400	Bad Request	Currency Code is either invalid or not supported. Please contact operations
EN-VAL-017	400	Bad Request	msisdn / sender_msisdn / receiver_msisdn is invalid, for phone number use international format (e.g., [phone])
EN-VAL-018	400	Bad Request	Invalid Bank Identifier - bankcode (BIC, routing number, sort code) or banksubcode (e.g. IFSC, branch code) is invalid
EN-VAL-019	400	Bad Request	Invalid Bank Account Number
EN-VAL-020	422	Unprocessable Entity	No whitelisted bank accounts associated to account: {email} were found
EN-VAL-021	400	Bad Request	Invalid transfer type
EN-VAL-022	400	Bad Request	Invalid coin
EN-VAL-023	400	Bad Request	Invalid payment provider
EN-VAL-024	404	Not Found	No corridor quotation found for prefunded account
EN-VAL-025	404	Not Found	No quotation found for the receiving country
EN-VAL-026	400	Bad Request	The receiving amount {receivingAmount} exceeds the per-transaction limit for the requested country. Limit: {paymentDetail?.limitLC}
EN-VAL-027	422	Unprocessable Entity	Failed. The amount exceeds your monthly limit
EN-VAL-028	400	Bad Request	Failed. You do not have sufficient {coin} balance to perform this transaction
EN-VAL-029	404	Not Found	The user account {accountNo} is invalid or has not been whitelisted yet
EN-VAL-030	400	Bad Request	Verification failed: invalid details
EN-VAL-031	404	Not Found	The user account {msisdin} is invalid or has not been whitelisted yet
EN-VAL-032	409	Conflict	User with this ID already exists
EN-VAL-033	409	Conflict	This {transferType} account is already linked to your email address
EN-VAL-034	400	Bad Request	Fee is not defined or amount entered is rejected by the receiving vendor (below min 1 USD equivalent). Please increase the amount and try again or contact operations
EN-VAL-035	400	Bad Request	Invalid provider selected. Please choose one of the following valid options: {validOptions}
EN-VAL-037	400	Bad Request	Invalid provider selected. Please choose one of the following valid options: {validOptions}
EN-VAL-038	400	Bad Request	Verification failed, invalid details
EN-VAL-039	400	Bad Request	Invalid beneficiary details
EN-VAL-040	422	Unprocessable Entity	User does not have any whitelisted mobile wallet

---

Network & Connection Errors

Network-level errors that typically require retry logic.

Code	Status	Message	Description
EAI_AGAIN	503	Service Unavailable	Temporary DNS resolution issue. Try again
ECONNABORTED	503	Service Unavailable	Request timed out. Please try again later
ECONNREFUSED	503	Service Unavailable	Could not connect to the service
ECONNRESET	503	Service Unavailable	Connection was reset. Please retry
ENETUNREACH	503	Service Unavailable	Network is unreachable. Check your connection
ENOTFOUND	503	Service Unavailable	Service is currently unreachable
ERR_NETWORK	503	Service Unavailable	Network error occurred. Please check your connection
Gateway Timeout	504	Gateway Timeout	Request timed out at gateway level

---

Client Configuration Errors

Errors related to client-side configuration or request formatting.

Code	Status	Message	Description
ERR_BAD_OPTION_VALUE	500	Internal Server Error	Internal configuration error. Contact support
ERR_BAD_REQUEST	500	Internal Server Error	Request configuration is invalid
ERR_CANCELED	400	Bad Request	Request was cancelled by the client
ERR_DEPRECATED	500	Internal Server Error	Deprecated configuration used. Please update client
ERR_FR_MAX_BODY_LENGTH_EXCEEDED	400	Bad Request	Request body is too large
ERR_FR_TOO_MANY_REDIRECTS	400	Bad Request	Request caused too many redirects
ERR_INVALID_URL	400	Bad Request	The requested URL is invalid

Resolution Steps:

• Update your client library to the latest version

• Reduce request payload size

• Verify request URLs are properly formatted

• Check for redirect loops in your implementation

---

HTTP Status Code Summary

Status Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters or data
401	Unauthorized	Authentication required or failed
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Resource conflict (e.g., duplicate)
422	Unprocessable Entity	Request understood but cannot be processed
423	Locked	Resource is locked
500	Internal Server Error	Server-side error occurred
503	Service Unavailable	Service temporarily unavailable
504	Gateway Timeout	Request timed out