RESTクライアント（Delphi内）：タイムアウト、再試行、HTTP 429（レート制限）に対してバックオフを伴う堅牢性

理論上、REST呼び出しは単純だ：リクエストを送る、レスポンスを受け取る、それで完了。しかし実運用での統合は、たいてい「間違った URL」によって失敗するのではなく、運用の周辺事象で破綻する：断続的なタイムアウト、短時間の DNS や TLS の問題、下流システムの過負荷、あるいは API ゲートウェイによる制限で発生する 429（Too Many Requests）。ここに、デモ・プロトタイプと長期運用可能な統合との決定的な違いがある。

この投稿では、RESTClient in Delphi を用いて堅牢な通信経路を確立する方法を示す：明確なタイムアウト定義、業務上および技術上安全な箇所に限定した的確なリトライ、レート制限を悪化させないバックオフ挙動。焦点は「きれいなコード」ではなく、負荷下での振る舞い、デバッグのしやすさ、明確なエラー分類、そして追加工数が本当に見合うかどうかの判断にある。

なぜ実環境でタイムアウト、リトライ、429が同時に発生するのか

企業ネットワーク内のREST呼び出しはめったに「直接インターネットに出る」ものではない。典型的にはプロキシの連鎖、TLS 終端、API ゲートウェイ、WAF (Web Application Firewall)、複数の内部ホップが存在する。各要素がそれぞれ異なるタイムアウトや制限を持ち得る。クライアント側のタイムアウトは次のいずれかを意味することがある：

• サーバが応答していない（過負荷、デッドロック、下流が詰まっている）。
• レスポンスは返ってきたが遅すぎる（経路の問題、パケットロス、輻輳）。
• 自分で締め出している：タイムアウトが短すぎる、あるいは UI／メインスレッドをブロッキングしている。

並行して、「単純な」リトライはしばしば状況を悪化させる：サーバが既に限界に達している場合、リトライは負荷を増幅し、小さなボトルネックを大きな障害に変える。429 の場合はさらに明白だ：レート制限は「送信を減らせ」あるいは「後で来い」という明確な指示だ。バックオフを組み込んでいないクライアントは、意図せず DoS ジェネレーターのように振る舞う。

したがって堅牢性は「どこでもリトライ」からは生まれない。むしろ一貫した意思決定モデルが必要だ：どのエラーが一時的（transient）で、どれが永続的か、どのリクエストがリトライ可能（冪等性を満たすか）か、そしてシステムの安定性を保つために待機時間をどう制御するか。

タイムアウトを正しく設定する：RESTClient in Delphi で「タイムアウト」は具体的に何を意味するか？

よくある落とし穴：「タイムアウト」は一義ではない。スタックによって複数のフェーズが存在する。Delphi-REST コンポーネントが多くを隠蔽していても、以下のモデルを頭に入れておくべきだ：

• 接続タイムアウト：TCP 接続が確立されるまでの時間（実装によっては DNS／TLS を含む）。
• 読み取り／レスポンスタイムアウト：サーバからバイトが届くか、レスポンスが完全に得られるまでの時間。
• 合計タイムアウト：リトライを含む呼び出し全体の上限時間。

実務では、短すぎるタイムアウトは長すぎるタイムアウトと同じくらい危険だ：人工的なエラーを発生させ、それがリトライされてさらなる負荷を生む。一方で、タイムアウトが長すぎるとワーカースレッドやキューのスロット、UI の応答性をブロックする。運用・管理上重要なのは、タイムアウトを（エンドポイント単位などで）設定可能にし、かつログに記録することだ。

実践的な推奨：単一数値ではなく二層

ビジネスソフトウェアにおけるREST呼び出しでは、二層の設定が有効だった：

• コールタイムアウト（各リクエスト毎）：ユースケースに合った現実的な上限。
• Job-Timeout（全体に対して）: バッチ処理や同期ジョブがある場合、全体の実行時間を制限し、正常に中断してください。

これにより、単一のAPI応答がいつまでも待機し続けるのを防ぎ、同時に夜間ジョブが多数の再試行のために「昼まで」走り続ける事態を回避できます。

再試行の判断：技術的ではなく業務的に

再試行が許されるかは純粋に技術的な問題ではありません。核心となる概念は冪等性（Idempotenz）です：リクエストが複数回実行されても1回実行したのと同じ効果をもたらす場合、そのリクエストは冪等であるといいます。典型例：GETは冪等、PUTも多くの場合（ターゲットオブジェクトを完全に設定する場合）冪等、DELETEも通常は冪等です。POSTは多くの場合冪等ではありません（例：「新しい受注を作成する」）。

なぜこれが決定的か。タイムアウトはサーバーがリクエストを処理したが応答がクライアントに届かなかったことを意味する場合があります。そこで盲目的にPOSTを再送すると重複が生まれます。これは運用上の典型的な「ゴーストエラー」です：アプリケーション側には「Timeout」と表示されるが、バックエンドには重複したデータが存在する、という状況になります。

安全な基盤：明確に再試行可能な操作にのみ再試行する

統合で有効だった堅牢なルール：

• GET：一時的なエラーに対して再試行可能。
• PUT/DELETE：APIが業務的に明確に定義している（例：リソースIDが安定している）かつサーバーが正しく冪等を実装している場合に再試行可能。
• POST：Idempotency-Key戦略（業務的に一意なリクエストIDを用い、サーバー側で重複を防止する）を採用している場合、またはPOSTが意味的に冪等である場合（稀だがあり得る）にのみ再試行可能。

APIを制御できない場合、ここで技術リードとして判断を下す必要があります：POSTでの再試行を許容しないことを受け入れて（その代わりにより良いエラーメッセージ／再同期メカニズムを構築する）、あるいはAPI提供者とIdempotency-Keyや重複排除可能なモデルについて合意する、のどちらかです。

429 Too Many Requests: Rate-Limits respektieren statt „weg-retryen“

HTTP 429は単なる「厄介なエラーメッセージ」ではなく、制御メカニズムです。企業環境では429は以下のような原因で発生することが多い：

• Token-Bucket/Leaky-Bucket制限（レートリミット）を持つAPIゲートウェイ。
• 1分／1時間あたりのテナント制限を持つクラウドAPI。
• 負荷の急増から自らを保護する内部サービス。

クライアントにとっての意味は：再試行は可だが、制御されたものにするということです。重要なのは二つ：

• Retry-Afterヘッダーを存在する場合は参照する（秒数またはHTTP日付）。
• バックオフを利用する（Retry-Afterがない場合や、さらにジッターを加える場合）。

最も一般的な落とし穴は、429を500と同様に扱うこと（「サーバーエラー、すぐ再試行」）。そうするとレート制限をさらに強化してしまいます。より適切なのは：429は積極的に待機することを示す信号であり、必要に応じて並列度を下げることです。

バックオフとジッター: ランダム性がないと全員同期的に崩壊する理由

指数バックオフとは、各失敗後に待機時間を増やす手法です（例: 200 ms、400 ms、800 ms …）。ジッターはランダム要素であり、多数のクライアントが同時に再試行するのを防ぎます。ジッターがないと実運用では次のような事がよく起きます: 制限に引っかかり50のクライアントが429を受け取り、全員が正確に1秒待機して同時に再送信する。結果として再び429が返り、「Thundering Herd」問題が発生します。

実務的なアプローチは「Full Jitter」や「Equal Jitter」です: バックオフのウィンドウを計算し、そのウィンドウ内でランダムな待機時間を選びます。細かい話に聞こえますが、運用上は安定した回復と継続的な再試行の差を生みます。

Ein sauberes Muster: REST-Aufrufe kapseln, statt überall Retry-Schleifen zu verstreuen

各呼び出し箇所に「場当たり的」にリトライ/バックオフを入れると、すぐに一貫性のない振る舞いになります: あるエンドポイントは積極的に再試行し、別のエンドポイントは全くしない、ログが抜け落ち、管理者には「断続的なエラー」しか見えません。堅牢にするには、中央の呼び出し経路を定義します:

• RESTClient/RESTRequestをラップするコンポーネントで、Policy（タイムアウト、リトライ、バックオフ）を適用する。
• 統一された結果オブジェクト: ステータスコード、所要時間、試行回数、必要に応じて最後の例外情報。
• 標準化されたロギング（Request-ID/Correlation-ID、エンドポイント、HTTPメソッド、関連ヘッダ）。

ここに追加のコードを書く価値があります: 再現可能な振る舞い、より良いログ、そして対象システムごとにポリシーを構成できる利点が得られ、アプリケーションを作り替える必要がなくなります。

Policy-Entscheidungsmatrix (kurz und praktisch)

ほとんどの統合では、ラッパー内で表現するシンプルなマトリクスで十分です:

• Retry bei: ネットワークエラー/接続断、408、429、502、503、504（API契約に応じて）。
• Kein Retry bei: 400/401/403/404（多くは設定/認証/リクエストエラー）、409/422（業務上の競合/バリデーション）、および冪等性キーなしのPOST。
• Max. Versuche: 小さく保つ（多くの場合2–4回で十分）、その代わり監視を強化する。
• Max. Backoff: 上限を設ける（例: 数秒〜1分程度）、さもなければ多くのワーカーをブロックしてしまう。

重要: これらのルールは普遍的ではありません。404は「最終的整合性（eventual consistency）」の文脈では一時的（transient）であることがあり得ますし、409はロック戦略によっては一時的になり得ます。違いは、それが意図的な例外かどうかであり、ランダムな振る舞いではないという点です。

Konkreter Randfall: Timeout nach POST – war es jetzt gespeichert oder nicht?

デバッガでは再現しにくい典型的なケースです: POST を送信（例: 「チケット作成」）、クライアントが Read-Timeout を受け取り、利用者が「もう一度」をクリックします。バックエンド側では既にチケットが存在することがあり、対策がなければ重複や不整合が発生します。

これを堅牢にするには、次の3つの戦略のいずれかが必要です:

• Idempotency-Key: 各業務処理ごとに一意のリクエストID（例: GUID）を生成し、Header として送信します。サーバーは重複排除された処理を保証します。
• Client-seitige Deduplizierung: 「pending requests」を独自ID付きでローカルに保持し、タイムアウト後にステータスチェック（例: 業務キーによる GET）を行います。手間がかかり、常に可能とは限りません。
• Kein Retry: 状態が不明であることを明確に報告し、手動または自動のリシンクプロセス（例: 後続の照合）を用意します。

運用向けの統合を構築する場合、「状態不明」は正当なカテゴリです。不確実性をコードで隠そうとしないでください。ログに残し、可視化し、照合の経路を確保してください。

Backoff-Design in der Praxis: Grenzwerte, Parallelität und Cancel

バックオフは単なる「Sleep」ではありません。アプリケーションのコンテキストに合わせて設計する必要があります:

• Parallelität: スレッドが20本あり全てが待機すると、20本すべてがブロックされます。サービスでは多くの場合許容されますが、デスクトップアプリでは好ましくありません。
• Cancel: ユーザーが中断したり、サービスが停止したり、ジョブが終了したりする場合、バックオフ待機は中断可能でなければなりません。そうでないと停止／シャットダウン処理がハングします。
• Fairness: 複数のエンドポイントが互いにリソースを奪い合わないようにする必要があります。レートリミットは多くの場合トークン単位やエンドポイント単位です。ラッパーはターゲットシステムごとに制御できるべきです。

適切なアプローチは: バックオフを小さな間隔で待機しつつキャンセルフラグ（例: Event/Token）を確認する関数に実装することです。これは贅沢ではありません: まさにこの箇所が、WindowsとLinuxのサービスが正常に停止するか、Service Control Manager コンソールで「ハング」するかを決定します。

Maximaldauer und „Budget“ pro Call

堅牢なリトライ実装は「max tries」だけでなく、時間予算も扱います。例: リトライを含めたコールの合計最大を 10 秒に制限します。そうすれば、タイムアウトの誤設定で単一の試行が突然 30 秒もブロックすることを防げます。管理者や運用にとっては非常に重要で、レイテンシのスパイクを抑え、キューを安定させます。

Debugging und Betriebsdiagnose: Ohne gute Logs sind Retries unsichtbare Fehlerverstärker

ログなしのリトライは危険です。結局「たまに遅くなる」だけの説明になってしまいます。堅牢にするには、例外を出力するだけでなくコンテキストを提供するログが必要です：

• Correlation-ID: 各呼び出しごとに生成し、すべてのリトライで保持するリクエストID。
• Attempt-Nummer und Delay（バックオフ）。
• HTTP-Status und ausgewählte Header（特に Retry-After、存在する場合は RateLimit-Header）。
• Dauer pro Versuch und Gesamtzeit。
• Endpoint（ホスト＋パス）、ただしログに機密データ（トークン、個人データ）を含めないこと。

技術責任者にとっては、これが閾値を調整するための手がかりにもなります。タイムアウトが「常に3秒で発生する」か（おそらく短すぎる）、あるいは429が波状に来ているか（並列度が高すぎる、バックオフが弱い、クライアント側のレート制限がない）を見分けられます。

典型的なログの落とし穴

• Zu viel Payload: JSONボディを丸ごとログするのは一見有用ですが、ファイルや添付で爆発的に増え、データ保護の問題を引き起こします。代わりにハッシュ／サイズ、Content-Type、必要に応じて機能フラグによる限定的なデバッグログを使ってください。
• Keine Unterscheidung Timeout vs. Cancel: 中断された呼び出しはタイムアウトと同じ意味でのエラーではありません。これを区別しないと管理者が幻のエラーを追いかけることになります。
• Retry verschluckt die erste Ursache: 試行1でTLSエラーが発生し試行2で成功した場合でも、TLSの揺らぎがあったことは記録しておきたい。それ自体が早期警告です。

Client-seitiges Rate-Limiting: Wenn du die Last selbst steuern musst

429はサーバー側の応答です。しかし多くの場面では、そもそも429を発生させる前にクライアント側でレートを抑える方が合理的です。特に次のような場合に重要です：

• バッチジョブがあり（例：夜間のデータ同期）、APIが1分あたりXリクエストのみ許可する場合。
• 複数のワーカー／スレッドを用いてリクエストを並列に発射している場合。
• 複数のプロセスインスタンスが稼働している場合（例：ターミナルサーバーや複数のサービス）。

実務的には、ターゲットシステムやAPIキーごとに小さなレートリミッター（例：Token-Bucket）を実装します。これにより429が減り、スループットが安定し、実行時間の予測がしやすくなります。運用とキャパシティ計画の観点では、多くの場合「もう一回リトライ」よりこちらの方が価値があります。

Wichtig: Rate-Limiter und Backoff ergänzen sich

レートリミッターは通常運用で制限内に収めます。バックオフは、それでも429や一時的な過負荷を受けた場合の反応です。バックオフしかないと常に「壁にぶつかって」ブレーキを踏む運用になりがちですし、レートリミッターだけだと、予期しない制限や共有クォータ（例：複数システムが同一のAPIキーを使う場合）に対して適切に反応できません。

セキュリティとコンプライアンス: Retries dürfen keine Auth-Probleme verschleiern

企業環境では、デプロイ後に最も頻繁に発生する「障害」は認証や認可に関するものです：期限切れトークン、クライアント認証情報の誤設定、プロキシの例外設定漏れなど。リトライはここでは無力であるだけでなく、ログを埋め、アカウントロックや認証エンドポイントに対するレート制限などの抑止機構を誘発して害を及ぼすことがあります。

実務ルール：401/403は決してリトライしない（意図的なトークンリフレッシュ処理を実装している場合を除く）。トークンリフレッシュを実装する場合は、リトライ機構と明確に分離してください：まずトークンを更新し、その後で一度だけ再送する。そしてリフレッシュが発生したことを明確にログに残します。

手間をかける価値がある場合とない場合

堅牢なリトライやバックオフはそれ自体が目的ではありません。次のいずれかに当てはまる場合に特に有用です：

• 統合が業務上重要である場合（例：受注処理、出荷、請求）。
• APIが外部提供である、または社内でも「ベストエフォート」で運用されており完全な制御ができない場合。
• バーストトラフィックが発生する（例：ジョブウィンドウ、月次締め）など、安定稼働を確保したい場合。
• サービス／デーモンとして稼働させており、計画的かつ確実に停止できる必要がある場合。

UI上で確認用の「GET」だけでユーザーが再クリックするのが前提であったり、クォータがなく非常に安定した社内環境でエラーが即座に可視化される場合は、優先度は下がります。それでも、適切なタイムアウト設定とロギングはほとんど常に有用です。

本番環境でのDelphi-RESTクライアント運用に向けた実践チェックリスト

• タイムアウト: エンドポイントごとに設定可能、現実的に設定し、全体の予算（合計時間）を定義する。
• リトライポリシー: HTTPメソッドと冪等性に基づいて決め、画一的に適用しない。
• 429ハンドリング: Retry-Afterを評価し、ジッター付きバックオフを行い、並列度を考慮する。
• 中断経路: バックオフ待ちを中断可能にする（サービス停止、ユーザーキャンセル）。
• ロギング: Correlation-ID、試行回数、遅延、所要時間、ステータス/ヘッダ — 秘密情報を含めない。
• 任意: バッチ/並列運用向けのクライアント側レートリミッタ。

結論: ロバストネスは振る舞いであり、万能のcatch-all例外ブロックではない

強力なRESTClient in Delphiを使えばREST呼び出しを素早く動かせます。しかし、本番での堅牢性を確保するには、タイムアウトを明確に定義し、リトライを業務的に安全化（冪等性の担保！）し、429のレート制限をバックオフとジッターで尊重する必要があります。このためのコードは複雑ではありませんが、集中管理され、設定可能で、適切に監視されることが重要です。そうすることで効果が現れます：突発的なチケットの減少、運用時の診断性向上、負荷下でも安定した統合。

既存のDelphiアプリケーションにそのようなリトライ／バックオフポリシーを適切に導入する、あるいは新規統合に合わせて設計したい場合は、お問い合わせください。

このテーマではDelphi Restclientのタイムアウトとリトライ戦略も重要です。本稿ではこれらの側面を整理し、日常運用で注目すべき点を示しています。

プロジェクトまたはモダナイゼーション案件をNet-Baseと相談する.