進階
Failure Codes 錯誤代碼
了解閃電網路支付失敗的錯誤代碼，包括 BOLT 4 定義的各種失敗類型及其處理方式。
12 分鐘
什麼是錯誤代碼？
當閃電網路支付失敗時，失敗節點會返回一個加密的錯誤訊息給發送者。 這些錯誤訊息包含標準化的錯誤代碼，幫助發送者理解失敗原因並決定如何重試。 錯誤代碼定義在 BOLT 4 中。
洋蔥加密錯誤： 錯誤訊息使用洋蔥路由的共享密鑰加密，只有發送者能解密並確定是哪個節點返回了錯誤。
錯誤類型分類
Error Code Structure Error code format (2 bytes): Bit 15 (BADONION): 1 = HMAC verification failed Bit 14 (PERM): 1 = Permanent error, don't retry Bit 13 (NODE): 1 = Node error, can try bypassing Bit 12 (UPDATE): 1 = Contains channel_update Bits 0-11: Specific error type code Error Categories: • Temporary errors (can retry) - Resources temporarily unavailable, insufficient balance, etc. • Permanent errors (don't retry) - Amount too small, CLTV expired, channel doesn't exist, etc. • Node errors - Node issues, can bypass this node and retry • Onion errors - HMAC failed, routing data corrupted
常見錯誤代碼
臨時錯誤（可重試）
TEMPORARY_NODE_FAILURE (0x2002) ├── 節點暫時無法處理支付 ├── 原因：節點忙碌、重啟中、維護中 └── 處理：稍後重試或繞過此節點 TEMPORARY_CHANNEL_FAILURE (0x1007) ├── 通道暫時無法轉發 ├── 原因：餘額不足、HTLC 數量限制 ├── 可能包含：channel_update └── 處理：選擇其他路徑重試 EXPIRY_TOO_SOON (0x100E) ├── CLTV expiry 太接近當前區塊 ├── 原因：支付處理太慢 └── 處理：使用更大的 CLTV delta 重試 MPP_TIMEOUT (0x0017) ├── 多路徑支付超時 ├── 原因：部分支付未能及時到達 └── 處理：重新發送所有部分 CHANNEL_DISABLED (0x1009) ├── 通道已停用 ├── 原因：對方節點離線或維護中 ├── 包含：channel_update（disabled 標誌） └── 處理：更新路由表，選擇其他路徑
永久錯誤（不重試）
INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS (0x400F) ├── 支付詳情錯誤（最終節點返回） ├── 原因： │ ├── payment_hash 不匹配 │ ├── 金額不正確 │ ├── 發票已過期 │ └── 發票已被支付 └── 處理：檢查發票是否正確 UNKNOWN_NEXT_PEER (0x400A) ├── 下一跳節點未知 ├── 原因：通道不存在或已關閉 └── 處理：更新路由圖，重新計算路徑 AMOUNT_BELOW_MINIMUM (0x100B) ├── 金額低於最小限制 ├── 原因：低於 htlc_minimum_msat ├── 包含：channel_update └── 處理：增加金額或選擇其他通道 FEE_INSUFFICIENT (0x100C) ├── 手續費不足 ├── 原因：低於通道要求的費率 ├── 包含：channel_update └── 處理：使用新費率重新計算 INCORRECT_CLTV_EXPIRY (0x100D) ├── CLTV expiry 值不正確 ├── 原因：不符合 cltv_expiry_delta ├── 包含：channel_update └── 處理：使用正確的 delta 重試 FINAL_INCORRECT_CLTV_EXPIRY (0x4012) ├── 最終節點的 CLTV 不正確 ├── 原因：expiry 不匹配發票要求 └── 處理：使用發票指定的 min_final_cltv_expiry FINAL_INCORRECT_HTLC_AMOUNT (0x4013) ├── 最終節點收到的金額不正確 ├── 原因：金額與發票不符 └── 處理：確保發送正確金額
洋蔥錯誤
INVALID_ONION_VERSION (0x8002) ├── 洋蔥版本不支援 └── BADONION 標誌 + PERM 標誌 INVALID_ONION_HMAC (0x8003) ├── HMAC 驗證失敗 ├── 原因：洋蔥資料被篡改或密鑰錯誤 └── 處理：路徑可能有問題 INVALID_ONION_KEY (0x8004) ├── 洋蔥密鑰無效 ├── 原因：無法解密下一層 └── 處理：重新計算洋蔥 INVALID_ONION_PAYLOAD (0x8016) ├── 洋蔥 payload 格式錯誤 ├── 原因：TLV 編碼錯誤 └── 處理：檢查發送端實現 INVALID_ONION_BLINDING (0x801A) ├── 盲化路由錯誤 ├── 原因：盲化點計算失敗 └── 處理：重新計算盲化路徑
完整錯誤代碼表
錯誤代碼速查表： 代碼 名稱 標誌 處理 ───────────────────────────────────────────────────────────────────── 0x0002 invalid_realm BADONION+PERM 不重試 0x0003 temporary_node_failure NODE 可重試 0x0004 permanent_node_failure PERM+NODE 不重試 0x0005 required_node_feature_missing PERM+NODE 不重試 0x0006 invalid_onion_version BADONION+PERM 不重試 0x0007 invalid_onion_hmac BADONION+PERM 不重試 0x0008 invalid_onion_key BADONION+PERM 不重試 0x0009 amount_below_minimum UPDATE 用新參數重試 0x000A fee_insufficient UPDATE 用新費率重試 0x000B incorrect_cltv_expiry UPDATE 用新 delta 重試 0x000C expiry_too_soon UPDATE 用更大 expiry 重試 0x000D incorrect_or_unknown_payment_details PERM 檢查發票 0x000E incorrect_payment_amount PERM 檢查金額 0x000F final_expiry_too_soon - 加大 CLTV 0x0010 final_incorrect_cltv_expiry PERM 用正確 CLTV 0x0011 final_incorrect_htlc_amount PERM 用正確金額 0x0012 channel_disabled UPDATE 選其他路徑 0x0013 expiry_too_far - 減小 CLTV 0x0014 invalid_onion_payload BADONION+PERM 檢查實現 0x0015 mpp_timeout - 重發所有部分 0x0016 invalid_onion_blinding BADONION+PERM 重算盲化路徑 0x0018 unknown_next_peer PERM 更新路由圖
錯誤訊息結構
Error Message Format update_fail_htlc message: • channel_id: 32 bytes • id: u64 (HTLC ID) • reason: encrypted error message Decrypted error message: • hmac: 32 bytes • failure_len: 2 bytes • failuremsg: failure_len bytes - failure_code: 2 bytes - data: depends on failure_code • pad_len: 2 bytes • pad: pad_len bytes Error with channel_update (UPDATE flag): • failure_code: 2 bytes • len: 2 bytes • channel_update: len bytes - signature: 64 bytes - chain_hash: 32 bytes - short_channel_id: 8 bytes - timestamp: 4 bytes - message_flags: 1 byte - channel_flags: 1 byte - cltv_expiry_delta: 2 bytes - htlc_minimum_msat: 8 bytes - fee_base_msat: 4 bytes - fee_proportional_millionths: 4 bytes - htlc_maximum_msat: 8 bytes (optional)
錯誤處理策略
更新路由資訊
收到帶 UPDATE 標誌的錯誤時，應該驗證並更新本地路由表中的通道資訊。 這包括費率、最小金額、CLTV delta 等參數。
避免失敗節點
收到節點錯誤時，應該在 Mission Control 中記錄。 後續路徑計算時暫時避開此節點或通道，直到懲罰期過後。
重試邏輯
臨時錯誤可以重試，永久錯誤應該放棄或使用完全不同的路徑。 設定最大重試次數避免無限循環。
錯誤識別
解密錯誤訊息時，使用共享密鑰逐層嘗試。 成功解密的層對應返回錯誤的節點。
Mission Control 整合
How Mission Control Uses Errors Processing after receiving error: 1. Decrypt error, identify failing node 2. Determine penalty severity based on error type 3. Update node/channel success probability 4. Use updated probability in next path calculation Penalty Strategy Example: Error Type Penalty Decay Time ---------------------------------------------------------------- TEMPORARY_CHANNEL_FAILURE Light 1 hour CHANNEL_DISABLED Medium 6 hours UNKNOWN_NEXT_PEER Heavy Permanent INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS None N/A Probability update formula: new_probability = old_probability * decay_factor Example: • Initial success probability: 95% • Received TEMPORARY_CHANNEL_FAILURE • Penalty: Success probability drops to 60% • After 1 hour, starts decay recovery • After 24 hours, returns to baseline probability
調試支付失敗
查看支付失敗原因： LND: # 查看支付歷史 lncli listpayments --include_incomplete # 查看特定支付 lncli trackpayment <payment_hash> # 詳細錯誤資訊 lncli sendpayment --debug_send ... CLN: # 查看支付狀態 lightning-cli listsendpays # 查看支付嘗試 lightning-cli listsendpays <bolt11> 常見失敗場景診斷： "TEMPORARY_CHANNEL_FAILURE" ├── 檢查：對方通道餘額 ├── 檢查：HTLC 數量是否達到上限 └── 解決：選擇其他路徑或稍後重試 "INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS" ├── 檢查：發票是否過期 ├── 檢查：金額是否正確 ├── 檢查：是否已支付過 └── 解決：請求新發票 "UNKNOWN_NEXT_PEER" ├── 檢查：目標通道是否存在 ├── 檢查：路由圖是否過時 └── 解決：同步路由圖並重試
相關資源
下一步： 了解 功能位 如何協商節點能力。
已複製連結