APIタイムアウトとは？仕組み・原因・安全な対処法 | Relvo
約1分で読めます
APIタイムアウトとは、呼び出し元や途中の中継先が、設定した時間内に応答を受け取れず、待機を打ち切ることです。応答がなかったことは、接続先の処理が実行されなかった証拠ではありません。 特に送信や登録のような操作では、再試行する前に処理結果と重複の危険を確認しましょう。
この記事の要点
- タイムアウトは待機の終了：どの区間で、何を待つ時間が切れたかを確認します。接続先の処理結果は別途調べる必要があります。
- 経路ごとに切り分ける：呼び出し元、ゲートウェイ、接続先の記録と制限時間を照合し、どこで待機が終わったかを探します。
- 再試行には条件がある：一時的な問題かどうかと、同じ操作を繰り返しても安全かどうかの両方を確認します。
- 書き込みの結果不明を残す：タイムアウトを未実行と決めつけず、状態照会や人による確認につなげます。
- 再試行にも上限を設ける：待機間隔にばらつきを持たせ、試行回数と処理全体の期限を制限します。
APIタイムアウトとは？待機を打ち切る仕組み
APIタイムアウトは、あらかじめ定めた待機時間を超えたときに、呼び出し元などが待つのをやめる仕組みです。長時間応答を待ち続けて接続や処理資源を占有する事態を防ぐために使います。
ただし、タイムアウトには複数の種類があります。名前が同じでも、何を計測するかはクライアントや設定によって異なります。
- 接続タイムアウト：接続の確立を待つ時間の上限です。
- 読み取りタイムアウト：応答データの受信を待つ時間に関する上限です。受信全体の時間か、データが届かない時間かは実装によって異なります。
- リクエスト全体の期限：一回の要求や業務操作全体に使える時間の上限です。再試行や待機時間を含むかも確認します。
例えば、接続に時間がかかる場合と、接続後に処理が長引く場合では、調べる場所が異なります。AWSの解説は、設定によってはDNSの名前解決やTLS接続の確立が計測範囲に含まれないこともあると説明しています。利用するライブラリの仕様で、計測の開始点と終了点を確かめてください。
タイムアウトと処理の失敗は同じではない
タイムアウトは「待っていた側が期限までに結果を得られなかった」という観測です。リクエストが届かなかった場合もあれば、接続先で処理が続いている場合や、処理は完了したものの応答を受け取れなかった場合もあります。
例えば、Google CloudのCloud Runでは、リクエストがタイムアウトすると接続が閉じられても、コンテナが処理を続ける場合があります。これは同サービスの具体例ですが、「待機終了と処理中止は別」という考え方を示しています。
タイムアウトはどこで起きる？呼び出し元・ゲートウェイ・接続先
一つのリクエストでも、経路にある各機器やサービスが別々の時間制限を持つことがあります。まず、実際の構成にどの層が存在するかを書き出します。
- 呼び出し元：アプリケーションやツール実行側が、接続や応答を待つ時間を制限します。クライアント側の例外として現れ、HTTP応答自体を受け取れない場合もあります。
- ゲートウェイやプロキシ：中継側が上流サービスの応答を待つ時間を制限します。中継側からタイムアウトを示すHTTP応答が返る場合もあります。
- 接続先のサービス：サービス自身や、その先のデータベースなどに時間制限がある場合があります。接続先が待機を打ち切ったとしても、さらにその先の処理まで停止したかは別に確認します。
例えば、呼び出し元の待機上限が5秒、中継先が10秒で、接続先が8秒で結果を返す構成を考えます。呼び出し元は5秒で待機を終える一方、接続先はその後に処理を終える可能性があります。これは説明用の例であり、推奨設定値ではありません。
HTTP 504のような応答を受け取った場合は、まず応答を返した層と、その層が何を待っていたかを調べます。ステータスだけで、最終的な接続先の処理状態までは断定しないようにしましょう。
APIタイムアウトの原因を切り分ける手順
原因を調べるときは、先に設定値を延ばすのではなく、どの層がいつ待機を終え、その時点で接続先に何が起きていたかを確認します。同じ要求を追える記録があると、通信の遅れと接続先の処理遅延を区別しやすくなります。
- 呼び出し元の情報を集める：発生時刻、対象API、操作の種類、経過時間、例外や受け取ったHTTP応答を確認します。接続前なのか、送信後なのか、応答待ちなのかも分かる範囲で記録します。
- 要求を各層で照合する：共通のリクエストIDやトレースIDが使える場合は、それを基に呼び出し元、中継先、接続先の記録を突き合わせます。IDが連携されていなければ、時刻や対象を手がかりにしつつ、同じ要求と断定できるか確認します。
- 各層の時間制限と実測時間を比べる：接続、応答待ち、一回の要求、処理全体について、設定値と実際の経過時間を比較します。SDKやジョブ基盤が自動再試行していないかも確認します。
- 接続先の状態を調べる：要求の受信、処理の開始・完了、依存先への待機、記録された結果を確認します。処理IDや状態照会APIがある場合は、それも利用します。
- 偏りを調べる：特定の時間帯、操作、入力量、接続先、初回接続などに集中していないかを比較します。接続先の負荷、ネットワーク、設定変更や障害情報も確認します。
記録が見つからないことだけで「要求は届かなかった」とは限りません。記録の欠落や照合できない可能性もあるため、根拠が足りなければ結果は不明として扱います。秘密情報や不要な個人情報を調査記録に残さないことも必要です。
設定時間を延ばす前に確認する
時間が足りない原因が、一時的な混雑なのか、恒常的に遅い処理なのか、設定が実態に合っていないのかで対処は変わります。応答時間の分布と利用者が待てる時間を見比べ、各層の設定と処理全体の期限を合わせて検討します。
AWSは、タイムアウトが短すぎると再試行が増え、逆に長すぎると待機中の資源を消費すると説明しています。値を延ばした後も遅延や負荷を測定し、長時間かかる処理は、受付後に状態を照会する非同期方式が使えるかも検討します。
タイムアウト後に再試行できるかを判断する
再試行を判断するときは、原因が一時的である可能性と、操作を繰り返しても安全かを別々に確認します。一時的な通信障害が疑われても、書き込みの重複を防げなければ、すぐに再送する理由にはなりません。
Google Cloudの再試行ガイドも、再試行の判断に応答と操作のべき等性の両方を挙げています。次は判断の出発点です。実際の対象や扱いは、接続先APIの仕様を優先してください。
- 一時的な問題が疑われる場合：通信の途切れ、一時的な過負荷などは、時間を置くと回復する可能性があります。APIが再試行可能と定め、安全に繰り返せる操作なら、上限付きで再試行を検討します。
- 条件を変えないと解消しない場合：入力内容の誤りや設定の不備などは、同じ要求を繰り返すより、原因を修正してから実行します。
- 書き込みの結果が不明な場合：登録、決済、投稿、送信などは、まず処理状態を照会します。照会できず重複防止の仕組みもない場合は、自動再送せず確認に回します。
429や5xxなどの応答が一時的な問題を示すことはありますが、コードだけで再試行の安全性が決まるわけではありません。APIごとの指示、待機時間の指定、操作の性質を合わせて確認しましょう。
べき等性とべき等キーで重複を防ぐ
べき等性とは、同じ操作を繰り返しても、一度行った場合と同じ状態になる性質です。一般に参照操作は再試行しやすい一方、新しい注文や投稿の作成は、繰り返すと複数作られるおそれがあります。HTTPメソッド名だけで安全と決めず、個々のAPIの契約を確認します。
操作によっては、特定の条件を付けた場合に限って安全に再試行できます。例えばCloud Storageでは、世代番号などの前提条件によって、条件付きでべき等になる操作が説明されています。
べき等キーは同じ操作の再送に使う
接続先がべき等キーに対応している場合、呼び出し元は一つの業務操作を識別するキーを用意し、応答が不明な場合の再送にも同じキーを使います。接続先がそのキーを使って重複を扱うことで、同じ操作が繰り返し実行されるのを防ぐ設計です。
キーの名前を送るだけで、どのAPIでも重複を防げるわけではありません。採用前に、対象操作への対応、保存期間、同時に同じキーが届いた場合の扱い、同じキーで内容が異なる場合の挙動、結果の取得方法を提供元の仕様で確認します。保存期間を過ぎた再送は、同じキーでも新しい要求として扱われる可能性があります。
例えば注文作成で応答が届かないときは、注文を探すための操作IDとキーを保持し、状態照会を優先します。再送が許される契約なら、同じ操作の同じ内容とキーを使い、別のキーを発行して新規注文として送り直さないようにします。
書き込み操作の認証・権限・承認も別途設計が必要です。べき等性は重複防止のための性質であり、その操作を許可してよいかの判断とは異なります。
安全な再試行には上限付きバックオフとジッターを使う
再試行が安全かつ有効と判断できた場合も、すぐに何度も送ると、障害中の接続先の負荷を増やすおそれがあります。AWSのガイドは、再試行間隔を伸ばすバックオフと、待機時間にばらつきを加えるジッターを紹介しています。
設計時には、次を一緒に決めます。
- 再試行する層：アプリ、SDK、中継先がそれぞれ再送すると、意図した以上の要求が発生します。実際の設定を確認し、どこが再試行を担うかを決めます。
- 待機時間：失敗するたびに待機の上限を増やす指数バックオフを使い、待機が長くなりすぎないよう上限を置きます。その範囲でランダムなばらつきを加えると、同時刻への再試行の集中を避けやすくなります。
- 総試行回数：初回を含めて何回まで送るかを明示します。「再試行3回」と「総試行3回」は同じではありません。
- 処理全体の期限：一回ごとの通信時間だけでなく、待機や結果の返却も含めます。残り時間が足りなければ、回数が残っていても次の試行を始めません。
- 停止と引き渡し：回復しない場合は上限で止め、失敗または結果不明と、その理由を呼び出し元に返します。
例えば、読み取り専用の照会で初回を含め最大3回まで試す場合、再送前の待機上限を順に増やし、その範囲内で待機時間をばらつかせます。これは考え方の例です。回数や秒数は、接続先の制限と業務の期限に合わせて決めます。提供元が再試行までの待機時間を指定する場合は、その指示と残り期限を照合し、期限に収まらなければ無理に再送しません。
AIエージェントのツール実行では「結果不明」を返す
AIエージェントが使うツールでも、タイムアウトを単純な「失敗」として返すと、モデルが同じ操作をやり直す可能性があります。ツールの実行側で、応答を受け取れなかったことと、外部操作の成否が不明であることを区別し、次に許される行動を明示します。
例えば、外部サービスへの投稿を依頼し、送信後に応答待ちが切れた場合を考えます。投稿が存在するか確認できるまでは、次のような情報を実行結果として保持します。
- 状態：結果不明。投稿が完了したとも、未実行とも判定しません。
- 操作の識別情報：後から照会できる操作ID、接続先の要求ID、使用したべき等キーなど、利用可能な情報を記録します。
- 分かっている範囲：送信を試みたこと、応答を受け取れなかったこと、状態照会の結果を区別します。照会自体が失敗した場合も「投稿なし」とは扱いません。
- 次の対応：状態を照会し、確認できなければ担当者に引き渡します。提供元の契約に基づいて安全な再送が可能と確認できるまで、新しい投稿を作り直しません。
ツールから「結果不明。投稿状態を確認してください」と返すだけでなく、実行側でも無条件の再送を防ぐことが必要です。状態照会で完了を確認できれば結果を返し、未実行と確認できた場合も、再送の可否はAPIの契約と業務上の条件に従って決めます。
まとめ
APIタイムアウトが示すのは、ある場所で応答を待つ時間が切れたことです。呼び出し元、中継先、接続先の記録を照合して待機が切れた場所を探し、書き込みの結果が不明なら、再送より先に状態確認を行います。
まずは一つのAPI操作を選び、各層の時間制限、実際の試行回数、結果不明時の確認方法を書き出してみてください。再試行できる操作には、べき等性と回数・時間の上限を組み合わせます。
Relvoは、エージェント向けツールやAPIをつなぐスマートルーターです。接続方法にかかわらず、タイムアウト時の結果確認と再試行の条件は、利用するAPIとアプリケーションの設計で確認する必要があります。
よくある質問
APIがタイムアウトしたら、処理は失敗していますか？
タイムアウトだけでは判断できません。接続先で処理が続いていたり、処理が完了していても応答だけを受け取れなかったりする可能性があります。書き込み操作は、操作IDなどを使って状態を確認してください。
タイムアウトしたAPIはすぐに再試行すべきですか？
必ずしもそうではありません。一時的な問題の可能性に加え、同じ操作を繰り返しても安全かを確認します。再試行する場合も、待機時間、回数、処理全体の期限に上限を設けます。
最初にどこを調べればよいですか？
呼び出し元で、発生時刻、経過時間、操作名、例外やHTTP応答を確認します。続いて同じ要求の記録をゲートウェイと接続先で照合し、どの層が待機を打ち切ったか調べます。
タイムアウトの設定を長くすれば解決しますか？
処理に必要な時間と設定が合っていない場合は、見直しが有効なことがあります。ただし、接続先の過負荷や遅い処理が原因なら、待ち時間を延ばすだけで原因は解消しません。応答時間と各層の制限を測定してから判断します。
べき等キーがあれば、どんな書き込みも再試行できますか？
いいえ。接続先がその操作でべき等キーをサポートし、同一キーの再送をどう扱うかが明確な場合に利用できます。保存期間や同時実行時の挙動も確認し、仕様の範囲内で再試行してください。