LINE APIの送信がタイムアウトしたら｜リトライキーで二重送信を防ぐ

LINEへの送信APIがタイムアウトしても、メッセージが送られている可能性があります。失敗表示だけを見てもう一度送ると、お客さんに同じ案内が二通届くことがあります。再試行に対応するAPIでは、最初の送信からリトライキーを指定し、送信内容と一緒に記録しておきます。

これは送信APIの再試行についての記事です。管理画面から手動で押した配信ボタンの取り消しや、LINEから届くWebhookの再送とは別の仕組みです。

最初の送信からキーを付ける

LINE Developersの再試行ガイドでは、X-Line-Retry-KeyにUUIDを指定する方法が示されています。対象はプッシュ、マルチキャスト、ナローキャスト、ブロードキャストです。対応していないAPIへ付けると400で拒否されるため、返信APIにも一律に付ける設計にはしません。

キーは最初のリクエストから24時間有効です。再試行では同じキーを使い、内容と送信先を変えません。失敗したあとに新しいキーを作ると、最初の送信と同じリクエストとして扱う目的を失います。最初にキーを付けていなかった送信へ、あとから付けても同じ条件の再試行にはできません。

公式ガイドに基づく判断は、次のように整理できます。実際のエラーについては、応答の詳細と対象APIも確認します。

受理済みは、端末で受信した証明ではありません。リトライキーも確実な配信を保証する機能ではありません。この区別を管理画面にも残し、API成功を「お客さんが読んだ」状態へ置き換えないようにします。

送信結果で次を変える。200番台：受理済み・再試行しない。409：同じキーで受理済み。500・タイムアウト：同じキー・内容・宛先で再試行。その他の400番台：繰り返す前に原因を確認。

図：最初からリトライキーを付けた対象APIで、24時間以内に再試行する場合の判断です。受理済みと端末での受信は別です。

再試行する前に、元の送信先と内容を確認できる記録が必要です。担当者が画面上で文章を修正した場合も、失敗した送信の内容を修正後の文章へ差し替えないようにします。

設計の例として、送信を開始する前に、送信の内部ID、対象チャネル、宛先の内部参照、内容の確定版、リトライキー、最初の実行時刻を記録します。試行ごとの結果は、その記録へ紐づけます。個人情報やアクセストークンを障害調査ログへ出す必要はありません。保存先の権限と保持期間は別に決めます。

同じ送信記録を複数の処理が同時に引き受けない制御も必要です。リトライキーを付けていても、処理ごとに別のキーを作ってしまえば、別々の送信になります。送信を確定する場所を一つにして、その記録を再試行処理へ渡します。

24時間を過ぎた送信を、新しいキーで自動的に送れば安全だとは限りません。最初のメッセージが届いていた可能性に加えて、予約日時や商品の条件が変わっている場合があります。

期限を超えたものは、受理状態が不明な送信として担当が確認できる場所へ残します。改めて案内が必要か、元の文章を使ってよいか、既に別の担当が返信していないかを見て判断します。確認待ちの送信を一覧から消してしまうと、担当もお客さんも、案内が止まった理由を追えなくなります。

管理画面に再送ボタンを置く場合は、未受理の再試行なのか、確認後の新しい送信なのかが分かる表示にします。担当者には、確定した結果と未確認の結果を分けて示してください。

再試行の間隔は短く詰めず、公式ガイドが案内するバックオフを検討します。試行回数や終了条件、担当に通知する条件も自社側で決めます。自動処理がいつまでも続く状態にせず、止まった送信を人が確認できるようにします。

テストは実際のお客さんへの配信ではなく、許可したテスト先または模擬応答で行います。受理後に応答だけを失う場面、同じキーで409が返る場面、期限切れ、担当の操作との競合を試し、送信の記録が重複しないかを確認してください。APIの全体像は、Messaging APIの基礎で整理しています。