錯誤碼與解決方案

錯誤碼參考

所有 API 響應返回 HTTP Code 200，通過 5 位數字的響應碼表達業務結果。

錯誤碼分類

代碼範圍	分類	描述
00000	成功	請求成功完成
10xxx	參數/校驗錯誤	無效參數或校驗失敗
20xxx	業務邏輯錯誤	業務規則違反或狀態錯誤
30xxx	數據狀態錯誤	數據一致性或版本衝突
40xxx	資源未找到	請求的資源不存在
50xxx	權限/認證錯誤	權限被拒絕或認證失敗
99999	系統錯誤	內部系統錯誤

完整錯誤碼列表

成功 (00000)

代碼	訊息	描述
00000	Success	請求成功完成

參數/校驗錯誤 (10xxx)

代碼	訊息	描述
10001	Invalid argument	一個或多個參數無效
10002	Missing required parameter	缺少必填參數
10003	Invalid parameter format	參數格式不符合要求
10004	Order amount must be greater than 0	訂單金額無效
10005	Expiration time cannot be earlier than current time	過期時間無效
10006	Currency not supported	不支持指定的幣種
10007	Invalid merchant	商戶 ID 無效
10008	Amount is not within the allowed range	金額超出最小/最大限制
10009	Amount precision is not within reasonable range	小數位數過多
10010	Invalid payment method	支付方式無效

業務邏輯錯誤 (20xxx)

代碼	訊息	描述
20001	Order already exists	商戶訂單號重複
20002	Order already paid	訂單已支付
20003	Order already cancelled	訂單已取消
20004	Order already closed	訂單已關閉
20005	Order expired	訂單已過期
20006	Order not payable	訂單當前狀態不可支付
20007	Invalid order status for this operation	當前訂單狀態不允許此操作
20008	Duplicate payment	重複支付
20009	Payment amount mismatch	支付金額不匹配訂單金額
20010	Refund amount exceeded	退款金額超過已支付金額
20011	Insufficient balance	帳戶餘額不足
20012	Payment timeout	支付處理超時
20013	Payment channel unavailable	支付通道當前不可用
20014	Transaction limit exceeded	超過單筆交易限額
20015	Daily limit exceeded	超過每日交易限額
20016	Payment method not supported	此訂單不支持該支付方式
20017	Risk control rejected	風控拒絕交易
20018	Refund not allowed	此訂單不允許退款
20019	Order cannot be cancelled	當前狀態不允許取消訂單
20020	Payment in progress	支付正在處理中
20021	Merchant not active	商戶帳戶未啟用
20022	Account frozen	帳戶已凍結
20023	Account disabled	帳戶已停用
20024	KYC verification required	需要 KYC 驗證
20025	Payment method expired	支付方式已過期
20026	Card declined	卡支付被拒絕
20027	Network error	網絡通信錯誤
20028	Settlement failed	結算處理失敗
20029	Withdrawal not allowed	不允許提款
20030	Blacklist user	用戶已被列入黑名單
20031	Address already allocated	充值地址已分配
20032	Address allocation failed	分配充值地址失敗
20033	Order query failed	查詢訂單失敗
20034	Deposit order creation failed	創建充值訂單失敗
20035	Insufficient paid amount	支付金額不足
20036	Withdrawal failed, please try again later	提款處理失敗
20037	Wallet line does not match wallet code	錢包配置不匹配
20038	Asset query failed	查詢資產餘額失敗
20039	Asset available not enough	可用資產餘額不足
20040	Failed to estimate miner fee	無法估算區塊鏈礦工費
20041	Conversion failed	貨幣轉換失敗
20042	Duplicate transfer order number	轉賬訂單號已存在
20043	Wallet code error	錢包代碼無效
20044	Network configuration error	區塊鏈網絡配置錯誤
20045	Coin not found	未找到加密貨幣
20046	Deposit address not found	未找到充值地址
20047	Exchange rate not found	匯率不可用
20048	Third party API error	外部 API 錯誤
20049	Address allocation failed error	地址分配系統錯誤
20050	Deposit order not found	充值訂單不存在
20051	Deposit order send record not found	未找到充值訂單發送記錄

數據狀態錯誤 (30xxx)

代碼	訊息	描述
30001	Data state inconsistent	數據狀態不一致
30002	Data version conflict, please retry	樂觀鎖衝突，需要重試
30003	Data has been modified	數據已被其他進程修改

資源未找到錯誤 (40xxx)

代碼	訊息	描述
40001	Order not found	訂單不存在
40002	Merchant not found	商戶不存在
40003	Payment record not found	支付記錄不存在
40004	Refund record not found	退款記錄不存在
40005	User not found	用戶不存在
40006	Account not found	帳戶不存在
40007	Channel not found	未找到支付通道
40008	Wallet not found	未找到錢包
40009	Transaction not found	未找到交易記錄
40010	Address not found	未找到地址
40011	Checkout session not found	結賬會話不存在
40012	FX rate not found	外匯匯率不可用
40013	Invalid currency	幣種代碼無效
40014	Invalid parameter	參數無效

權限/認證錯誤 (50xxx)

代碼	訊息	描述
50001	Unauthorized access	需要認證
50002	Forbidden	禁止訪問
50003	Signature verification failed	請求簽名無效
50004	Invalid API key	API 密鑰無效或未找到
50005	Token expired	認證令牌已過期
50006	Invalid token	認證令牌無效
50007	Access denied	拒絕訪問資源
50008	Rate limit exceeded	請求過多，超過速率限制
50009	IP not whitelisted	請求 IP 未列入白名單

交易所支付錯誤 (501xx)

代碼	訊息	描述
50101	Failed to connect to exchange API	無法連接到交易所服務
50102	Failed to create exchange order	交易所訂單創建失敗
50103	Failed to query exchange order	交易所訂單查詢失敗
50104	Invalid exchange signature	交易所簽名驗證失敗
50105	Exchange order not found	交易所訂單不存在
50106	Exchange order expired	交易所訂單已過期
50107	Unsupported currency for exchange	交易所不支持該幣種
50108	Failed to process exchange webhook	交易所 Webhook 處理失敗
50109	Failed to close exchange order	無法關閉交易所訂單
50110	Failed to fetch exchange certificate	交易所證書獲取失敗

系統錯誤 (99999)

代碼	訊息	描述
99999	System error, please try again later	發生內部系統錯誤

---

常見錯誤排查

錯誤: "Invalid signature" (簽名無效)

可能原因:

1. JSON 格式不匹配 (格式化 vs 壓縮)
2. API 密鑰錯誤
3. 簽名計算不正確
4. 時間戳不匹配

解決方案:

1. 驗證 JSON 是壓縮的:

   // 檢查 JSON 中是否有換行符或多餘空格
   console.log('包含換行符:', body.includes('\n'));
   console.log('包含多餘空格:', body.includes('  '));

2. 檢查簽名組成部分:

   console.log('簽名字符串:', stringToSign.replace(/\n/g, ' | '));
   console.log('請求體哈希:', bodyHash);

3. 驗證 API 密鑰:

   • 確保 API 密鑰中沒有多餘的空白字符
   • 檢查您使用的是否是正確的環境 (測試環境 vs 生產環境)

錯誤: "Invalid or expired timestamp." (時間戳無效或已過期)

可能原因:

1. 時間戳不是毫秒級 (10 位數字而非 13 位)
2. 服務器時間未同步
3. 請求耗時過長 (>5 分鐘)

解決方案:

1. 使用毫秒:

   // ✅ 正確 (13位數字)
   const timestamp = Date.now(); // 1737554400000
   
   // ❌ 錯誤 (10位數字)
   const timestamp = Math.floor(Date.now() / 1000); // 1737554400

2. 同步服務器時間:

   # Linux/macOS
   sudo ntpdate -u pool.ntp.org
   
   # 或啟用 NTP 服務
   sudo systemctl enable chronyd
   sudo systemctl start chronyd

錯誤: "Invalid timestamp format" (時間戳格式無效)

可能原因:

• 時間戳長度不是 13 位數字

解決方案:

const timestamp = Date.now().toString();
console.log('時間戳長度:', timestamp.length); // 應該是 13

相關文檔

• 重要注意事項 - 查看時間戳和 JSON 格式要求
• 簽名算法 - 了解簽名計算詳情
• 安全最佳實踐 - 了解安全集成建議