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

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

# 概要

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

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

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

注意

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

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

リトライキーを利用してAPIリクエストを再試行できるエンドポイントを利用する際は、以下のフローを参考に実装してください。

Retry API Request Flowchart

# （1）リトライキーは常に指定する

以下のエンドポイントを利用する際は、X-Line-Retry-Keyリクエストヘッダーにリトライキー（任意の方法で生成した16進表記のUUID）を常に指定します。

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

プッシュメッセージを送るときにリトライキー（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: 123e4567-e89b-12d3-a456-426614174000' \
-d '{
    "messages": [
        {
            "type": "text",
            "text": "Hello, user"
        }
    ]
}'

一度目のAPIリクエストからリトライキーを指定してください

X-Line-Retry-Keyを指定しなかったAPIリクエストは、再試行できません。

上記以外のAPIの場合

上記以外のAPIでは、リトライキーを指定できません。X-Line-Retry-Keyをリクエストヘッダーに含めると、APIリクエストは拒否されステータスコード400が返されます。

# （2）必要に応じてAPIリクエストを再試行する

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

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

注意

リトライキーの有効期間は、最初にリクエストを試行してから24時間です。リトライキーを使ったリクエストの再試行は24時間以内に実行するように設計してください。
同じリトライキーを使ったリクエストは、すべて完全に同じ内容になるようにしてください。同じリトライキーで、異なる内容のメッセージや宛先に送信した場合の挙動は保証されません。

再試行の間隔について

リトライキーを使った再試行でも、APIリクエスト数にカウントされるため、頻繁に再試行を繰り返すとAPIのレート制限に達する恐れがあります。
サーバーやネットワーク障害時の負荷軽減のため、再試行間隔は「エクスポネンシャルバックオフ (opens new window)」により制御することをお勧めします。

# APIリクエストを再試行した場合のレスポンス

APIリクエストが受理されたかどうかでレスポンスが異なります。

リクエストIDはリクエストごとに異なります

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

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

リトライキーを指定しない場合のレスポンスと同じです。

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

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

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

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"}

『Messaging APIリファレンス』の「APIリクエストを再試行する」セクション

概要 APIリクエストの再試行のフロー（1）リトライキーは常に指定する（2）必要に応じてAPIリクエストを再試行する関連ページ