Claude APIのリクエストタイムアウトと「ストリーミングを強く推奨」

通常、あなたとモデルの間には3つのタイムアウトがあります。SDKのもの、中間サービスのもの、長時間のストリーミングなし呼び出しに対するプロバイダー独自のルールです。最も短いものが適用されます。SDKだけを延長しても、解決したと思った後も問題が続くのはそのためです。

エラー

two shapes

# Rejected before generating, for a long non-streaming request:
{"type":"error","error":{"type":"invalid_request_error",
 "message":"Streaming is strongly recommended for operations that may take
 longer than 10 minutes."}}

# Or the client-side companion, with no response at all:
APITimeoutError: Request timed out.

原因と対処法の概要

原因	対処法
長いストリーミングなし生成	ストリーミングしてください。長い完了処理は待つのではなく、ストリーミングすることが想定されています。
SDKクライアントのタイムアウトが生成時間より短い	延長してください。ただし中間サービスの制限も延長しなければ、何も変わりません。
プロキシ、ロードバランサー、またはリクエストを制限するサーバーレス関数	チェーン内で最も短い制限を見つけてください。そこが到達している制限です。
接続は受け付けられたが、その後応答がない	遅い応答ではなくハングです。最初のバイトまでの時間を別途制限してください。

数分を超える可能性のあるものはすべてストリーミングする

制限を回避できるだけでなく、ストリーミングは生存確認のシグナルになります。トークンが届いているならモデルは動作中なので、ハングと進行の遅さを区別できます。単一のブロッキング呼び出しでは、タイムアウトが発生するまでこの2つは同じに見えます。

SDKだけでなく、チェーン内のすべてのタイムアウトを延長する

ほとんどの人はクライアントだけを変更して終わります。しかし、リバースプロキシやサーバーレスプラットフォームが新しいクライアントタイムアウトより短くリクエストを制限していれば、その制限が勝ち、症状は変わりません。

client.py

from anthropic import Anthropic

# Client timeout is only one of the limits in play.
client = Anthropic(api_key=KEY, timeout=600.0)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8192,
    messages=[{"role": "user", "content": prompt}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

最初のバイトまでの時間を合計時間とは別に制限する

これは異なる対処が必要な2つの異なる障害です。短い最初のバイト期限なら死んだ接続をすぐ検出でき、余裕のある合計期限なら本当に長い生成を完了できます。1つの統合タイムアウトでは両方に対応できません。

リトライを追加する前に安全にする

あなた側でタイムアウトしたリクエストが、上流では完了している可能性があります。処理に副作用がある場合、または呼び出しごとに課金される場合は、リトライループを追加する前に自分のレイヤーで冪等性を実装してください。

Kunavo経由で呼び出している場合

Kunavoは数値を自ら公開しているため、利用者が推測する必要はありません。上流のレスポンスヘッダーを最大240秒待ちます。ストリーミングなしの応答は通常、完了してからヘッダーを送るため、それ以上必要なストリーミングなし呼び出しはゲートウェイ経由では完了しません。ストリーミングしてください。240秒の制限はヘッダー到着までにのみ適用され、ヘッダーが届いた瞬間に解除されるため、長いストリームが途中で切られることはありません。ゲートウェイにはストリームの長さに対するその他の制限はありません。終了させるのは無通信です。上流から300秒間バイトが届かない場合、またはあなたとの接続で600秒間バイトが届かない場合です。同期画像、動画、音楽ルートは、レンダリングに正当に数分かかるため、600秒のウィンドウ内で最大540秒間接続を保持します。ヘッダー前にタイムアウトしたリクエストはチャネル障害として扱われ、設定されている場合はモデルの次のチャネルで再試行され、コスト0として記録されます。

よくある質問

タイムアウトしたリクエストは課金されますか？

Kunavoでは請求されません。失敗したリクエストはコスト0として記録されます。プロバイダーから直接請求を受ける場合、請求の有無は実際に生成が行われたかどうかによって異なります。

ストリーミングで制限を回避できるのはなぜですか？

応答は数秒以内に開始し、接続がアクティブな状態で維持されるため、1回の無通信期間がタイムアウトを発生させるほど長くなりません。

クライアントのタイムアウトはどのくらいにすべきですか？

現実的に想定される最長の生成より長くし、短い別個の最初のバイト期限と組み合わせてください。長い統合タイムアウトを1つだけ設定すると、すべてのハングが数分間の停止になります。

Claude APIのリクエストタイムアウトと「ストリーミングを強く推奨」 — 10分ルール

エラー