Anthropic SDKのAPIConnectionError: Request timed outの解決方法

リクエストがタイムアウトする理由

APIConnectionError: Request timed outが表示される場合、通常はClaudeがレスポンスの生成を完了する前に、ローカルスクリプトが待機を停止したことを意味します。Anthropic SDKのデフォルト設定は60秒です。1分という時間は長く感じられますが、Claude 3.5 SonnetやOpusが膨大なプロンプトを処理したり、2,000ワードを超える複雑な技術文書を作成したりするには、不十分なことがよくあります。

anthropic.APIConnectionError: Request timed out.

主な原因

出力ボリュームの多さ: 3,000ワードの詳細なブログ記事やフルコードベースの作成を依頼すると、60秒の制限を超えることがよくあります。
大規模なコンテキストウィンドウ: 10万トークンのドキュメントを送信すると、最初の単語が生成されるまでに数秒の「プリフィル（事前充填）」時間が必要になります。
プロキシの設定: 企業のファイアウォールやロードバランサー（Nginxなど）は、30秒または60秒以上アイドル状態が続く接続を強制終了することがあります。
ネットワークの不安定さ: モバイルホットスポットの高レイテンシや混雑したVPNにより、接続が切断されることがあります。

ステップ1：デフォルトのタイムアウト時間を増やす

最も手っ取り早い解決策は、SDKの待機時間に余裕を持たせることです。ほとんどの本番アプリケーションでは、複雑なタスクに対して2分（120秒）または5分（300秒）のタイムアウトを設定するのが安全です。

Pythonでの設定

Pythonでは、timeout引数に秒単位で指定します。クライアントに対してグローバルに設定することも、特定の呼び出しに対して個別に上書きすることも可能です。

from anthropic import Anthropic

# グローバルタイムアウトを2分に設定
client = Anthropic(
    api_key="your_api_key",
    timeout=120.0 
)

# または、1つの重いリクエストに対して5分のタイムアウトを設定
response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=4096,
    messages=[{"role": "user", "content": "これら5つの50ページのPDFを分析して..."}],
    timeout=300.0 
)

Node.jsでの設定

JavaScript SDKではミリ秒単位を使用します。設定したい秒数に1,000を掛けてください。

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: 'my_api_key',
  timeout: 120 * 1000, // 120秒
});

// リクエストごとの上書き（5分）
const message = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20240620',
  max_tokens: 4096,
  messages: [{ role: 'user', content: 'システムアーキテクチャ全体を生成して。' }],
}, { timeout: 300000 });

ステップ2：ネットワークプロキシの設定を確認する

企業プロキシを利用している場合、コード側のタイムアウト設定だけが問題ではない可能性があります。多くのプロキシには独自の内部タイマーがあります。コードで300秒に設定していても、プロキシが60秒で接続を切断する場合、依然としてタイムアウトエラーが発生します。

ターミナルで環境変数が有効になっていることを確認してください：

export HTTP_PROXY="http://your-proxy-server:8080"
export HTTPS_PROXY="http://your-proxy-server:8080"

プロのヒント: Nginxをリバースプロキシとして使用している場合は、proxy_read_timeoutの設定を確認してください。この値はSDKのタイムアウト設定と同じか、それ以上に設定する必要があります。

ステップ3：ストリーミングに切り替える（推奨される方法）

ストリーミングは、タイムアウトを防ぐための最も堅牢な方法です。4,000トークンのレスポンス全体が完了するのを待つのではなく、Claudeはデータを断片的に送信します。これにより接続が「アクティブ」に保たれ、ネットワーク側でリクエストが停止したと判断されるのを防ぎます。

Pythonでのストリーミング例

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "長編の研究論文を書いて。"}],
    model="claude-3-5-sonnet-20240620",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

解決策をテストする方法

エラーが再発するのをただ待つのではなく、以下の手順で設定を確認できます：

強制的に失敗させる: timeout=0.001に設定します。コードが即座にAPIConnectionErrorをスローすれば、正しい設定箇所を編集していることが確認できます。
高負荷テスト: タイムアウトを120.0に設定し、Claudeに「コンピュータの歴史について2,000ワードのエッセイを書いて」と依頼します。
時間の計測: ストップウォッチを使用します。リクエストが75秒後に正常に完了すれば、新しいタイムアウト設定が正しく機能しています。

最終チェックリスト

SDKの更新: Anthropicは頻繁に接続処理の改善を行っています。pip install -U anthropic または npm install @anthropic-ai/sdk@latest を実行してください。
DNSの確認: 1秒未満でタイムアウトが発生する場合、DNSの問題である可能性が高いです。ping api.anthropic.com を試して、マシンがサーバーに到達できるか確認してください。
リトライロジック: SDKはデフォルトで2回リトライします。インターネット接続が特に不安定な場合は、max_retries=5 のように設定して回数を増やすことができます。