日本語

# 失敗したAPIリクエストを再試行する

# 概要

Messaging APIを使って応答メッセージやプッシュメッセージを送信した際に、ステータスコード500番台のエラーが発生したり、リクエストがタイムアウトした場合、ユーザーに正しくメッセージが配信されていない可能性があります。しかし、同じAPIリクエストを続けて実行してしまうと、最初のAPIリクエストが正しく受理されていた場合、ユーザーは同じメッセージを二度も受信することになります。

同じ値のリトライキー（X-Line-Retry-Key）を含んだAPIリクエストを何度実行しても、必ず一度だけ処理されるため、同じ処理の重複を防ぐことができます。すでにリクエストが受理されている場合は、再リクエストは拒否されステータスコード409を返します。

リトライキーを使うことで重複してAPIリクエストが処理されることなく、安全にリクエストを再試行することができます。

注意
  • X-Line-Retry-Keyにより、メッセージの重複を気にせず安全にAPIリクエストを再試行することができますが、メッセージの確実な配信を保証するものではありません。もしAPIリクエストが一度でもLINEプラットフォームに受理（HTTPステータスコード200番台）された場合、その後ユーザがLINE公式アカウントをブロックしたなどの理由で正しく配信ができなかったとしても、同じリクエストを再試行することはできません。
  • リトライキーの有効期間は、最初にリクエストを試行してから24時間です。リトライキーを使ったリクエストの再試行は24時間以内に実行するように設計してください。

# APIリクエスト再試行の設計

下記のとおりレスポンスステータスコードにしたがって、APIリクエストを再試行するように設計します。

ステータスコード 説明 再試行要否
500 Internal Server Error 内部サーバーのエラーです。 ✅ 再試行することで成功する可能性があります。
タイムアウト ネットワーク障害などでリクエストが失敗しています。 ✅ 再試行することで成功する可能性があります。
409 Conflict 同じリトライキーを持つAPIリクエストがすでに受理されています。 ❌ すでにリクエストは受理されています。
その他の400番台 リクエストに問題があります。 ❌ 再試行しても結果は変わりません。

# APIリクエストの再試行のフロー

ステータスコード500番台発生時やリクエストがタイムアウトした場合に限り、リトライキーを使ったAPIリクエストを再試行するように実装します。リトライキーを使った再試行でも、APIリクエスト数にカウントされるため、頻繁に再試行を繰り返すとAPIのレート制限に達する恐れがあります。

再試行の間隔について

サーバーやネットワーク障害時の負荷軽減のため、再試行間隔は「エクスポネンシャルバックオフ (opens new window)」により制御することをお勧めします。

Retry API Request Flowchart

# リトライキーが利用可能なAPI

送信方法 APIリファレンス
プッシュメッセージ プッシュメッセージを送る
マルチキャストメッセージ マルチキャストメッセージを送る
ナローキャストメッセージ ナローキャストメッセージを送る
ブロードキャストメッセージ ブロードキャストメッセージを送る
上記以外のAPIの場合

上記以外のAPIでX-Line-Retry-Keyをリクエストヘッダーに含めた場合、リクエストは拒否されステータスコード400が返ります。

# リクエストヘッダー

ヘッダー 値
X-Line-Retry-Key 任意の方法で生成した16進表記のUUID（例：123e4567-e89b-12d3-a456-426614174000）

# リクエストの例

curl -v -X POST https://api.line.me/v2/bot/message/push \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {CHANNEL_ACCESS_TOKEN}' \
-H 'X-Line-Retry-Key: {UUID}' \
-d '{
    "messages": [
        {
            "type": "text",
            "text": "Hello, user"
        }
    ]
}'
注意
  • X-Line-Retry-Keyの有効期間は、最初にリクエストを試行してから24時間です。
  • 同じリトライキーを使ったリクエストは、すべて完全に同じ内容になるようにしてください。同じリトライキーで、異なる内容のメッセージや宛先に送信した場合の挙動は保証されません。

# レスポンス

同じリトライキーで複数のリクエストを実行した場合、それぞれのリクエストには異なるリクエストIDが割り当てられます。

また、すでにリトライキーを含んだAPIリクエストが受理されている場合、同じリトライキーでリクエストを実行すると、ステータスコード409と受理されたリクエストのリクエストIDがx-line-accepted-request-idとしてレスポンスヘッダーに含まれます。

# 受理されたリクエストのレスポンス例

HTTP/1.1 200 OK
x-line-request-id: 123e4567-e89b-12d3-a456-426655440001

# 一度受理されたリクエストを再試行した際のレスポンス例

HTTP/1.1 409 Conflict
x-line-request-id: 123e4567-e89b-12d3-a456-426655440002
x-line-accepted-request-id: 123e4567-e89b-12d3-a456-426655440001
 
{"message":"The retry key is already accepted"}