LINE X-Line-Retry-Key：送信タイムアウトを重複なく再試行するには
対応する LINE Messaging API でメッセージを送る場合は、最初のリクエストから X-Line-Retry-Key を付けてください。タイムアウトや再試行可能なサーバー障害が起きたら、同じキー、宛先、内容で再試行します。新しい論理リクエストごとに16進表記の UUID を生成し、そのキーが受理済みであることを示す 409 が返ったら停止します。新しいキーへの交換は再試行ではありません。この仕組みは有効期間内の重複受理を防ぐもので、ユーザーへの到達保証ではありません。
要点
- 対象は push、multicast、narrowcast、broadcast。すべての LINE API に使えるわけではありません。
- エラーの後ではなく、送信前にキーと元のリクエストを永続化します。
- キーの有効期間は、LINE の仕様では最初のリクエストから24時間です。
- リクエスト受理、ユーザーへの配信、受信 webhook の応答は別々に管理します。
X-Line-Retry-Key が防ぐ重複
タイムアウトで分かるのは、アプリケーションがレスポンスを受け取れなかったことだけです。LINE 側ではすでに送信要求を受理している可能性があります。試行のたびに UUID を変えると、不明な結果を別の独立したリクエストに置き換えてしまいます。
LINE の再試行ガイドでは、キー付きのリクエストが一度受理されると、同じキーを使った後続の試行は重複として拒否されます。キーは初回から必要です。キーなしの送信がタイムアウトしてから付け足しても、元の送信をさかのぼって保護できません。
| 送信方法 | 公式に記載されたリトライキー対応 |
|---|---|
| Push | 対応 |
| Multicast | 対応 |
| Narrowcast | 対応 |
| Broadcast | 対応 |
| Reply messages を含むその他の API | この対応一覧の対象外。ヘッダーを一律に付けない |
未対応 API にこのヘッダーを付けると 400 になると LINE は説明しています。また、これは LINE MINI App の通知トークンによる送信とは別の仕組みです。そちらの障害は Service Message API のエラー対応ガイドで確認してください。
ネットワーク呼び出しより先に記録する
以下はアプリケーション設計の提案であり、LINE API の追加フィールドではありません。
業務操作の識別子、チャネル、送信方法、完全なリクエスト本文、リトライ UUID、初回試行時刻、再試行期限、処理状態を永続的な送信レコードに保存します。宛先と本文は自社の保持方針に従って保護してください。アクセストークンは安全な設定から取得し、ジョブや通常のログには保存しません。
保存後に初めて送信します。再試行では保存済みのキーとリクエストを読み込み、変更された注文情報や顧客情報から本文を作り直さないでください。LINE は、同じキーで再試行するときに宛先や内容を変えないよう明記しています。
業務操作には一意の識別子を設け、ワーカーのジョブ取得やロックも実装します。これがないと、同じ処理に対して別々のワーカーが異なる UUID を生成し、両方が受理される可能性があります。キーが重複排除するのはそのキーのリクエストであり、業務上同じ意味の別ジョブではありません。
一つの LINE 公式アカウントに複数ツールが接続する場合は、送信の担当システムを決めます。複数ツール接続のチェックリストはチャネル共有の境界を扱い、ローカルの outbox は個々の送信処理の所有権を扱います。
実際の結果から次の動作を決める
LINE のステータス別再試行ルールに従い、成功以外をすべて再送対象にしないでください。
| 結果 | 推奨するワーカーの処理 |
|---|---|
2xx | 受理を記録し、再試行を終了 |
| タイムアウト、再試行可能なサーバー障害 | 同じキーと本文を使い、予算内で再試行を予約 |
キー受理済みを示す 409 | x-line-accepted-request-id を保存し、受理済みとして終了 |
その他の 4xx | 同じ要求の再試行を止め、リクエストや制限を調査 |
| 期限切れで受理の有無が不明 | 自動でキーを交換せず、照合または担当者の確認へ |
重複受理のレスポンスにある x-line-accepted-request-id は成功したリクエストを識別します。個々の試行に付く x-line-request-id とは分けて保存してください。ステータス、時刻、機密情報を除いた診断情報を残し、エラー文言だけで分岐しないようにします。
LINE は指数バックオフを推奨し、再試行も API のレート制限に数えられると説明しています。スケジューラーには試行回数の上限を設け、24時間の有効期間を越えて再試行を予約しないでください。起点は初回リクエストであり、再試行するたびに24時間へ戻るわけではありません。アプリケーション側の期限は、それより保守的に設定できます。
期限が切れても、不明な結果は不明なままです。新しいキーは新たな送信判断であり、先に受理されたメッセージと重複する恐れがあります。通常の復旧としてキーを交換せず、照合または明示的な承認を挟みます。
受理と配信を混同しない
LINE は、リトライキーが確実な配信を保証するものではないと明記しています。たとえばユーザーが公式アカウントをブロックしている場合、受理から配信成功を推定できません。一度受理されたリクエストを同じキーで繰り返しても、配信の修復にはなりません。
画面上でも「LINE が受理」と「顧客が既読」を分けます。同様に、自社 webhook が成功を返したことは受信の確認であり、返信が送信された証拠ではありません。
UnifyPort の契約は別に扱う
UnifyPort の非公式インターフェースはメッセージングアカウントを接続し、message.received などの正規化イベントを配信します。同じ LINE 公式アカウントの Messaging API チャネルに追加する送信ツールではなく、公開送信仕様にも X-Line-Retry-Key の対応は記載されていません。
送信の再試行を設計する前に、テキストメッセージ仕様を確認してください。LINE の24時間の期間や重複受理レスポンスをそのまま適用してはいけません。トレース用 ID も、それだけで冪等性を保証するものではありません。
受信側では signing_secret を設定し、X-Device-Timestamp、ドット、未加工のリクエスト本文を連結した値の HMAC-SHA256 で X-Device-Signature を検証します。応答と再試行は webhook 配信仕様に従ってください。受信イベントの重複排除と送信の重複排除は、別々の問題です。
公式アカウント固有の送信機能が必要なら、公式 Messaging API を使います。一般アカウント接続へ切り替えても、すでに公式 API から送った結果不明のリクエストは解決しません。
FAQ
最初のタイムアウト後にキーを作れますか？
元のリクエストを保護することはできません。対応 API の初回試行からキーを含める必要があります。
409 なら新しい UUID で送ればよいですか？
同じキーが受理済みという意味なら、送らないでください。受理済みリクエスト ID を保存し、その操作の再試行を終了します。
同じキーのまま宛先を変更できますか？
できません。内容と宛先は元の要求と同一にします。業務内容の変更は、再試行の書き換えではなく別の判断が必要です。
すべての LINE メッセージ API に使えますか？
いいえ。公式に挙げられた対応方法だけです。MINI App service messages や UnifyPort の送信に転用しないでください。
次の作業と出典
送信ワーカーが停止した後も、同じキーと同じリクエストを復元できるか確認してください。まずローカルのモックで検証し、その後に管理された送信テストを行います。アカウント接続型の実装では UnifyPort の送信仕様を確認してください。
公式資料の確認日：2026-09-28。
メッセージ連携を安定したプロダクトパイプラインへ。
まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。