Microsoft Graphの429を安全に復旧する｜JSON batch内の失敗とRetry-Afterを確認

Microsoft GraphのJSON batchで外側のHTTPステータスが200でも、中に入れた要求がすべて成功したとは限りません。batch内の一部だけ429になっている場合、成功済みの要求までまとめて再送せず、個々の応答ID・ステータス・Retry-Afterを確認します。

この記事は、Graph連携の担当者が、batch全体の受付と各要求の結果を分け、throttlingを受けた要求だけを安全に再開する手順です。403の権限不足や、送信後の結果不明とは別に扱います。

外側200と内側のステータスを分ける

Microsoftのthrottling資料は、batch内の要求を個別に制限判定し、一部が429でもbatch自体は200で成功する場合を説明しています。HTTP clientの成功判定だけで処理完了へ進めず、responsesの各要素を確認します。Microsoft：Graph throttling guidance（新しいタブで開く）

表は横にスクロールできます

記録	何を判定するか
外側のHTTPステータス	batch送信自体の結果
各responseのid	元の要求との対応
各responseのステータス	成功、429、別の失敗
各responseのheaders	Retry-After等の指示
各responseのbody	resource固有のエラー内容

batch内の応答が送った順序と同じとは限らないため、配列の位置だけで対応付けません。送信時のidと、method・resource・業務上の対象を保存しておき、返されたidで照合します。Microsoft：Combine multiple HTTP requests using JSON batching（新しいタブで開く）

再送候補を要求IDの集合で決める

次は架空の応答を整理した例です。実Graph APIへ送信した結果ではありません。秒数は説明用で、サービスの固定待機時間を示しません。

表は横にスクロールできます

要求ID	内側ステータス	Retry-After	次の扱い
R1	201	なし	成功として記録し、重ねて作成しない
R2	429	5秒	待機後の再送候補
R3	429	15秒	待機後の再送候補
R4	400	なし	内容を調べる。429用再試行へ混ぜない

この例で429の再送集合はR2・R3です。まとめて再送するなら、両方の待機指定を満たす時刻を選びます。Microsoftの資料も、失敗した要求をJSON内のRetry-Afterに従って再試行し、必要ならその最大値を待って新しいbatchにまとめる方法を案内しています。

ただし400や403等まで、時間を置けば直るものとして扱いません。成功・再試行候補・内容修正が必要な失敗・結果不明を分けて記録します。

SDKの自動再試行を思い込まない

通常の単独requestに対するSDKの再試行機能が、batch内の429も自動で再送するとは限りません。Microsoftのthrottling資料は、batchに含まれたthrottled requestが自動再試行されない点を注意しています。使うSDKの版とbatch APIの動作を確認してください。

一方、独自再試行を外側へ追加する場合は、SDK内部の処理と二重になっていないかを確認します。送信回数、待機、内側ステータスを記録し、一つの429が多数の再送へ増幅しないようにします。

表は横にスクロールできます

確認する箇所	見たいこと
SDK・バージョン	利用中のbatch処理と再試行の範囲
アプリ側再試行	対象ID、最大試行、打切り条件
queue・jobの再実行	成功要求を再び含めないか
待機管理	各応答の指定を満たしているか

Retry-Afterがない場合は、公式資料の指数backoff方針を参照し、最大回数や打切りを決めます。常に同じ短い間隔でbatch全体を再送する実装にはしません。

依存する要求と結果不明を別に扱う

一つの要求が前の結果へ依存している場合、失敗した要求だけを機械的に抜き出しても、必要な前提が満たされない場合があります。元の要求の依存関係、必要なresource ID、成功済みの処理を確認して、次に送る要求を組み立てます。

外側の応答を受け取れなかった場合も、一部が既に適用された可能性を考えます。明確に429が返った個別要求と同じ扱いにせず、業務IDや対象resourceの状態を確認してから再送します。作成、更新、削除、読取りでは、同じ要求を繰り返す影響が違います。

復旧の確認目的で、本番の作成・通知を無条件に再実行しないでください。対象の副作用と、重複を検出する方法を先に決めます。

throttlingの再発を要求量から見る

待機後に一度成功しても、同じ負荷を繰り返せば再び429へ達するかもしれません。resourceごとの処理量、同時実行、不要なpolling、取得するデータの範囲を見直します。Graph全体で一つの固定上限だと決めず、対象serviceの制限と利用パターンを確認します。

利用できる場合は差分取得や変更通知も検討します。ただし新しい通知や同期方式を導入することと、今回の失敗要求を正しく処理済みにすることは別の課題です。まず未完了IDを明確にし、その後に再発防止を整理します。

各要求の最終状態をそろえて完了にする

元batchの全IDについて、成功、再送成功、修正待ち、結果不明の最終状態を残します。再送したbatchの外側が200になっただけで、最初のR1〜R4をすべて完了へ変えないでください。

表は横にスクロールできます

合格条件	残す記録
応答対応	元要求IDと各response IDが照合できる
待機	429ごとの指定と実際の再送時刻
重複防止	成功済み要求を再送していない
最終結果	全IDの成功・失敗・未確認が分かる
再発防止	要求量・並列度・監視の見直し箇所

本文は公式仕様に基づく診断と復旧設計です。実際のGraph APIへの接続、throttling再現、SDKの再試行動作やresource更新を検証した報告ではありません。