LINE X-Line-Retry-Key：傳送逾時後如何安全重試
使用支援重試鍵的 LINE Messaging API 傳送訊息時，應在第一次請求加入 X-Line-Retry-Key。若遇到逾時或可重試的伺服器錯誤，使用相同 key、收件人與內容重試。每個新的邏輯請求產生一個十六進位 UUID。若 409 表示這個 key 已被受理，就應停止，不要換 key 再傳。這能在規定期間內防止重複受理，但不保證使用者實際收到訊息。
重點整理
- Push、multicast、narrowcast、broadcast 支援重試鍵，不代表所有 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 的通知權杖流程。若處理的是該介面，請參考 Service Message API 錯誤排查指南，不要套用這套重試契約。
先保存重試紀錄，再進行網路呼叫
以下是應用程式設計建議，不是額外的 LINE API 欄位。
建立持久化傳送紀錄，保存業務操作識別碼、channel 身分、傳送方法、完整請求內容、重試 UUID、首次嘗試時間、重試截止時間及處理狀態。依保留政策保護收件人資料與訊息。存取權杖應從安全設定讀取，不要放入工作紀錄或一般日誌。
先完成儲存才發送。每次重試都載入已保存的 key 與請求，不要根據可能已變動的訂單或客戶資料重新組裝訊息。LINE 明確要求，重用 key 時不能更改內容或收件人。
業務操作應有唯一識別碼，worker 也需要工作認領機制或鎖。否則兩個 worker 可能為同一件事各產生一個 UUID，兩次請求都能被受理。重試鍵只辨識同 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 明確提醒，重試鍵不保證訊息可靠送達。例如使用者已封鎖 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 跑通傳送，再用標準事件把所有入站訊息接回業務系統。