LINE X-Line-Retry-Key：發送逾時後如何安全重試
使用支援重試 key 的 LINE Messaging API 發送訊息，應在第一次請求加入 X-Line-Retry-Key。遇到逾時或可重試的伺服器故障後，沿用同一個 key、相同收件人及內容。每個新的邏輯請求產生一個十六進制 UUID。如果 409 表示該 key 已獲受理，就應停止，而不是換 key 再發。這能在指定時限內防止重複受理，但不保證用戶實際收到訊息。
重點
- Push、multicast、narrowcast 和 broadcast 支援重試 key，並非所有 LINE API 都適用。
- 發送前先持久化 key 和原始請求，不要出錯後才建立。
- LINE 規定 key 自首次請求起 24 小時有效。
- 請求受理、用戶收到訊息、入站 webhook 確認，是三種不同結果。
X-Line-Retry-Key 保護甚麼
逾時只代表應用程式沒有收到回應，不代表 LINE 未受理發送。每次嘗試都換 UUID，會將不確定結果變成另一個獨立請求。
LINE 的請求重試指南說明：帶 key 的請求一旦受理，後續使用相同 key 的請求會被視為重複。key 必須從第一次請求就存在。不帶 key 的請求逾時後再補上，不能追溯保護之前的發送。
| 發送方式 | 官方文件列出的支援情況 |
|---|---|
| Push | 支援 |
| Multicast | 支援 |
| Narrowcast | 支援 |
| Broadcast | 支援 |
| 其他 API，包括 reply messages | 不在這份支援清單內，不要一律附加此標頭 |
LINE 表示，不支援的 API 若附加這個標頭，會回傳 400。這亦不同於 LINE MINI App 的通知 token 流程。若正在處理該介面，應參考 Service Message API 錯誤排查指南，不要直接套用本文。
先保存重試紀錄，再發出網絡請求
以下屬應用程式設計建議，不是新增的 LINE API 欄位。
建立持久化發送紀錄，保存業務操作識別碼、channel 身分、發送方法、完整請求內容、重試 UUID、首次嘗試時間、截止時間及處理狀態。按資料保留政策保護收件人資料及訊息內容。存取 token 應從安全設定讀取，不要放進工作紀錄或一般日誌。
先儲存，再發送。重試時載入已保存的 key 和請求，不要根據可能已變動的訂單或客戶資料重新組裝訊息。LINE 明確要求，重用 key 時內容及收件人都不能改。
為業務操作設定唯一識別碼，並用工作認領機制或鎖控制 worker。否則兩個 worker 可能為同一件事分別產生 UUID，兩個請求都獲受理。重試 key 只辨識相同 key 的請求，不會知道兩項獨立工作其實有相同目的。
多個工具共用 Official Account 時，先指定每種發送動作由哪個系統負責。多工具接入檢查清單處理共用 channel 的邊界；本地 outbox 則管理每項發送工作的歸屬。
按實際結果決定下一步
遵循 LINE 的狀態碼重試規則，不要把所有非成功回應都視為再次發送的許可。
| 實際結果 | 建議的 worker 行為 |
|---|---|
2xx | 記錄已受理，停止重試 |
| 逾時或可重試的伺服器故障 | 在預算內以原 key、原請求安排重試 |
409，表示 key 已受理 | 保存 x-line-accepted-request-id，記錄先前已受理並停止 |
其他 4xx | 停止原樣重試，調查請求或限制 |
| 超過重試期限，仍未知是否受理 | 交由核對或人手處理，不要自動換 key |
重複受理回應中的 x-line-accepted-request-id 指向成功請求；x-line-request-id 則識別個別請求嘗試。兩者需要分開保存。記錄狀態、時間及已遮蔽敏感資料的診斷資訊，不要只根據錯誤文字作判斷。
LINE 建議使用指數退避，並指出重試亦計入 API 速率限制。排程器應限制嘗試次數，且不應安排超出 key 的 24 小時有效期的重試。有效期由首次請求計算，不會每次重試都重新開始。應用程式可以採用更保守的截止時間。
期限屆滿後，未知結果仍是未知。新 key 是新的發送決定，可能重複之前已受理的訊息。應先核對或取得明確批准，不要把換 key 當作一般修復步驟。
已受理不等於已送達
LINE 明確提醒：重試 key 不保證訊息可靠送達。例如用戶已封鎖 Official Account，就不能從請求受理推斷已送達。受理後不斷提交相同 key，不是修復送達問題的方法。
應用狀態要分清「LINE 已受理」和「客戶已讀」。自己的 webhook 接收器回傳成功，亦只確認入站投遞，不代表出站回覆已經發送。
UnifyPort 採用另一套契約
UnifyPort 的非官方介面連接訊息帳戶，提供 message.received 等標準化事件。它不是同一個 LINE Official Account Messaging API channel 內的另一個發送工具，公開發送文件亦沒有列明支援 X-Line-Retry-Key。
實作 UnifyPort 發送重試前，先閱讀文字訊息介面。不要直接移植 LINE 的 24 小時期限或重複受理回應。追蹤識別碼也不自動等於冪等保證。
接收入站事件時設定 signing_secret，用 X-Device-Timestamp、一個點及原始請求本文計算 HMAC-SHA256，驗證 X-Device-Signature。確認及重試行為應遵循 webhook 投遞文件。入站事件去重與出站發送去重解決不同問題，完成其中一項不代表另一項也已完成。
需要 Official Account 原生發送功能時，應使用官方 Messaging API。改用普通帳戶介面，不能修復先前透過官方 API 發出但結果不明的請求。
常見問題
第一次逾時後才建立 key 可以嗎？
不能用它保護之前的請求。支援此功能的 API 必須從首次嘗試就帶上 key。
收到 409，是否應換 UUID 再發？
若它表示相同 key 已受理，就不應再發。保存成功請求識別碼，結束這項操作的重試。
保留 key，但改收件人可以嗎？
不可以。LINE 要求內容及收件人跟原始請求一致。業務動作有變時，應另行決定，而不是修改重試工作。
所有 LINE 訊息 API 都適用嗎？
不是。只適用於官方列出的支援方法，不能直接用於 MINI App service messages 或 UnifyPort 發送介面。
下一步與參考資料
檢查一個出站 worker：程序中斷後，能否恢復同一個 key 和同一份請求？先以本地模擬服務測試，再進行受控的實際發送。若採用訊息帳戶接入，請參考 UnifyPort 發送文件。
官方資料核對日期：2026-09-28。
令訊息接入變成一條穩定嘅產品管線。
先用統一嘅 API 跑通發送，再用標準事件將所有入站訊息接返去業務系統。