Error Codes and Solutions

Error Code Reference

All API responses return HTTP Code 200, with business results expressed through a 5-digit response code.

Error Code Categories

Code Range	Category	Description
00000	Success	Request completed successfully
10xxx	Parameter/Validation Errors	Invalid parameters or validation failures
20xxx	Business Logic Errors	Business rule violations or state errors
30xxx	Data State Errors	Data consistency or version conflicts
40xxx	Resource Not Found	Requested resource does not exist
50xxx	Authorization/Authentication Errors	Permission denied or authentication failed
99999	System Error	Internal system error

Complete Error Code List

Success (00000)

Code	Message	Description
00000	Success	Request completed successfully

Parameter/Validation Errors (10xxx)

Code	Message	Description
10001	Invalid argument	One or more arguments are invalid
10002	Missing required parameter	A required parameter is missing
10003	Invalid parameter format	Parameter format does not meet requirements
10004	Order amount must be greater than 0	Order amount is invalid
10005	Expiration time cannot be earlier than current time	Invalid expiration time
10006	Currency not supported	The specified currency is not supported
10007	Invalid merchant	Merchant ID is invalid
10008	Amount is not within the allowed range	Amount exceeds min/max limits
10009	Amount precision is not within reasonable range	Too many decimal places
10010	Invalid payment method	Payment method is not valid

Business Logic Errors (20xxx)

Code	Message	Description
20001	Order already exists	Duplicate merchant order ID
20002	Order already paid	Order has already been paid
20003	Order already cancelled	Order has been cancelled
20004	Order already closed	Order has been closed
20005	Order expired	Order has expired
20006	Order not payable	Order cannot be paid in current state
20007	Invalid order status for this operation	Operation not allowed for current order status
20008	Duplicate payment	Payment already processed
20009	Payment amount mismatch	Paid amount does not match order amount
20010	Refund amount exceeded	Refund amount exceeds paid amount
20011	Insufficient balance	Account balance insufficient
20012	Payment timeout	Payment processing timeout
20013	Payment channel unavailable	Payment channel is currently unavailable
20014	Transaction limit exceeded	Single transaction limit exceeded
20015	Daily limit exceeded	Daily transaction limit exceeded
20016	Payment method not supported	Payment method not supported for this order
20017	Risk control rejected	Transaction rejected by risk control
20018	Refund not allowed	Refund is not allowed for this order
20019	Order cannot be cancelled	Order cannot be cancelled in current state
20020	Payment in progress	Payment is currently being processed
20021	Merchant not active	Merchant account is not active
20022	Account frozen	Account has been frozen
20023	Account disabled	Account has been disabled
20024	KYC verification required	KYC verification is required
20025	Payment method expired	Payment method has expired
20026	Card declined	Card payment was declined
20027	Network error	Network communication error
20028	Settlement failed	Settlement processing failed
20029	Withdrawal not allowed	Withdrawal is not allowed
20030	Blacklist user	User is blacklisted
20031	Address already allocated	Deposit address already allocated
20032	Address allocation failed	Failed to allocate deposit address
20033	Order query failed	Failed to query order
20034	Deposit order creation failed	Failed to create deposit order
20035	Insufficient paid amount	Paid amount is insufficient
20036	Withdrawal failed, please try again later	Withdrawal processing failed
20037	Wallet line does not match wallet code	Wallet configuration mismatch
20038	Asset query failed	Failed to query asset balance
20039	Asset available not enough	Insufficient available asset balance
20040	Failed to estimate miner fee	Cannot estimate blockchain miner fee
20041	Conversion failed	Currency conversion failed
20042	Duplicate transfer order number	Transfer order number already exists
20043	Wallet code error	Invalid wallet code
20044	Network configuration error	Blockchain network configuration error
20045	Coin not found	Cryptocurrency not found
20046	Deposit address not found	Deposit address not found
20047	Exchange rate not found	Exchange rate not available
20048	Third party API error	External API error
20049	Address allocation failed error	Address allocation system error
20050	Deposit order not found	Deposit order does not exist
20051	Deposit order send record not found	Deposit order send record not found

Data State Errors (30xxx)

Code	Message	Description
30001	Data state inconsistent	Data state is inconsistent
30002	Data version conflict, please retry	Optimistic lock conflict, retry required
30003	Data has been modified	Data has been modified by another process

Resource Not Found Errors (40xxx)

Code	Message	Description
40001	Order not found	Order does not exist
40002	Merchant not found	Merchant does not exist
40003	Payment record not found	Payment record does not exist
40004	Refund record not found	Refund record does not exist
40005	User not found	User does not exist
40006	Account not found	Account does not exist
40007	Channel not found	Payment channel not found
40008	Wallet not found	Wallet not found
40009	Transaction not found	Transaction record not found
40010	Address not found	Address not found
40011	Checkout session not found	Checkout session does not exist
40012	FX rate not found	Foreign exchange rate not available
40013	Invalid currency	Currency code is invalid
40014	Invalid parameter	Parameter is invalid

Authorization/Authentication Errors (50xxx)

Code	Message	Description
50001	Unauthorized access	Authentication required
50002	Forbidden	Access forbidden
50003	Signature verification failed	Request signature is invalid
50004	Invalid API key	API key is invalid or not found
50005	Token expired	Authentication token has expired
50006	Invalid token	Authentication token is invalid
50007	Access denied	Access to resource denied
50008	Rate limit exceeded	Too many requests, rate limit exceeded
50009	IP not whitelisted	Request IP is not whitelisted

Exchange Payment Errors (501xx)

Code	Message	Description
50101	Failed to connect to exchange API	Cannot connect to exchange service
50102	Failed to create exchange order	Exchange order creation failed
50103	Failed to query exchange order	Exchange order query failed
50104	Invalid exchange signature	Exchange signature verification failed
50105	Exchange order not found	Exchange order does not exist
50106	Exchange order expired	Exchange order has expired
50107	Unsupported currency for exchange	Currency not supported by exchange
50108	Failed to process exchange webhook	Exchange webhook processing failed
50109	Failed to close exchange order	Cannot close exchange order
50110	Failed to fetch exchange certificate	Exchange certificate fetch failed

System Error (99999)

Code	Message	Description
99999	System error, please try again later	Internal system error occurred

---

Common Error Troubleshooting

Error: "Invalid signature"

Possible Causes:

1. JSON format mismatch (formatted vs compressed)
2. Incorrect API key
3. Incorrect signature calculation
4. Timestamp mismatch

Solutions:

1. Verify JSON is compressed:

   // Check if JSON contains line breaks or extra spaces
   console.log('Contains line breaks:', body.includes('\n'));
   console.log('Contains extra spaces:', body.includes('  '));

2. Check signature components:

   console.log('Signature string:', stringToSign.replace(/\n/g, ' | '));
   console.log('Body hash:', bodyHash);

3. Verify API key:

   • Ensure there are no extra whitespace characters in the API key
   • Check if you're using the correct environment (test vs production)

Error: "Invalid or expired timestamp"

Possible Causes:

1. Timestamp is not in milliseconds (10 digits instead of 13)
2. Server time is not synchronized
3. Request took too long (>5 minutes)

Solutions:

1. Use milliseconds:

   // ✅ Correct (13 digits)
   const timestamp = Date.now(); // 1737554400000
   
   // ❌ Wrong (10 digits)
   const timestamp = Math.floor(Date.now() / 1000); // 1737554400

2. Synchronize server time:

   # Linux/macOS
   sudo ntpdate -u pool.ntp.org
   
   # Or enable NTP service
   sudo systemctl enable chronyd
   sudo systemctl start chronyd

Error: "Invalid timestamp format"

Possible Causes:

• Timestamp length is not 13 digits

Solutions:

const timestamp = Date.now().toString();
console.log('Timestamp length:', timestamp.length); // Should be 13

Related Documentation

• Important Notes - Check timestamp and JSON format requirements
• Signature Algorithm - Learn signature calculation details
• Security Best Practices - Learn secure integration recommendations