Claude APIのrequest-idをサポート問い合わせで使う方法

Claude APIのレスポンスには必ずrequest-idヘッダーが付きます。req_018EeWyXxfu5pfWkrYcMdjWGのような値で、エラーレスポンスのJSON本体にもrequest_idフィールドとして同じ値が入ります。サポートに問い合わせるときはこのIDを添えるだけで調査が早くなりますが、取得方法は言語によって「プロパティを読むだけ」のSDKと「raw responseに切り替える」SDKに分かれます。本記事ではこの差分と、Claude Platform on AWSで2つのIDが返る事情を扱います。

request-idはどこで確認できるか

request-idはレスポンスヘッダーとして全リクエストに付与されます。成功したリクエストでも失敗したリクエストでも値は入り、エラー時はレスポンスボディのerrorオブジェクトと並んでrequest_idフィールドにも同じ値が複製されます。

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

つまり成功レスポンスからIDを取るにはヘッダーを読む必要がありますが、エラーレスポンスならボディのJSONを見るだけで済みます。SDKの例外オブジェクトがrequest_idを属性として持っていれば、catchブロックの中でヘッダーを意識せずに取得できます。言語別の例外クラス対応はClaude APIのエラー形式とSDK例外クラスの言語別対応表にまとめています。

curlで生のレスポンスヘッダーを確認する場合は、-D -でヘッダーを標準出力に出し、-o /dev/nullで本体を捨てます。

curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

CLIからantコマンドで呼び出す場合は、--debugフラグを付けるとrequest-idヘッダーが標準エラー出力に表示されます。

SDK別の取得方法 — プロパティ組とraw response組

Python・TypeScriptは最も手数が少なく、レスポンスオブジェクトのプロパティを読むだけでrequest-idが取れます。

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }]
});
console.log("Request ID:", message._request_id);

_request_idとアンダースコア始まりの命名になっている点に注意が必要です。ボディの中身とは別枠のメタ情報であることを示す命名で、通常のレスポンスフィールドと混同しないようにします。

C#・Go・Java・PHPの4言語は、通常のレスポンスオブジェクトにrequest-idが直接生えていません。raw responseのアクセサーに切り替えて、HTTPレスポンスそのものからヘッダーを読む形になります。

using var response = await client.WithRawResponse.Messages.Create(new MessageCreateParams
{
    Model = Model.ClaudeSonnet5,
    MaxTokens = 1024,
    Messages = [new() { Role = Role.User, Content = "Hello, Claude" }]
});
Console.WriteLine($"Request ID: {response.RequestID}");

Rubyだけはさらに毛色が異なり、SDKがレスポンスをパースする前の生HTTPレスポンスを受け取るミドルウェア経由でしか取得できません。request_optionsに渡したラムダが、SDKの内部処理をラップする形で呼ばれます。

request_id = nil
read_request_id = lambda do |request, call_next|
  response = call_next.call(request)
  request_id = response.headers["request-id"]
  response
end
 
client.messages.create(
  model: Anthropic::Model::CLAUDE_SONNET_5,
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  request_options: { middleware: [read_request_id] }
)
puts "Request ID: #{request_id}"

どのエラーでrequest-idを添えるべきか

すべてのエラーでサポートに問い合わせるべきというわけではありません。Claude APIのHTTPエラーは、実装側の修正で解決するものと、時間経過や再試行で解決するものに分かれます。

公式ドキュメントが名指しでrequest-idの利用を勧めているのは500エラーです。「内部エラーが起きた場合は、指数バックオフで再試行し、それでも解決しなければrequest-idを添えてサポートに連絡する」という手順が明記されています。400番台の大半は実装側の修正で完結するため、闇雲に全エラーへrequest-idを添付する運用は問い合わせ対応側の負荷を増やすだけで効果が薄いことになります。

ストリーミングレスポンスでは、200を返したあとにエラーイベントが届くケースがあり、この場合は通常のHTTPステータスコードによる分岐が効きません。エラーイベントの形はストリーミングAPIのドキュメントで個別に定義されていますが、レスポンスヘッダー自体は接続確立時に一度だけ送られるため、request-idの取得タイミングはストリーミングでも非ストリーミングでも変わりません。

anthropic-organization-id・anthropic-workspace-idも同じ経路で読める

request-idと並んで、レスポンスヘッダーにはanthropic-organization-idとanthropic-workspace-idも含まれます。実際のレスポンスヘッダーは次のような形です。

HTTP/1.1 200 OK
request-id: req_018EeWyXxfu5pfWkrYcMdjWG
anthropic-organization-id: 0d0e7a3b-52f1-4c7e-9a51-3f6f2f7c1b9e
anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

anthropic-workspace-idは、そのリクエストのAPIキーやアクセストークンが解決したワークスペースのID(wrkspc_接頭辞)です。Default Workspaceのリクエストでも値は入ります。このヘッダーが付かないケースが2つあります。①資格情報がワークスペースに解決しないリクエスト(Admin APIなど)②認証が完了する前にリクエストが失敗した場合(401エラーなど)です。401のような認証エラーでは、そもそもどのワークスペースのキーかを特定できないため、ヘッダー自体が省略されます。

読み取り方法はrequest-idと完全に同じで、Python・TypeScriptならプロパティ、それ以外のSDKならraw responseアクセサーです。「どの言語がどの経路か」を一度覚えれば、request-id・anthropic-organization-id・anthropic-workspace-idの3つすべてに同じ知識を使い回せます。複数ワークスペースを横断して運用しているチームでは、ログにこの3点セットを残しておくと、後から「どの組織・ワークスペースの、どのリクエストで起きたか」を1本のIDだけでなく相互に突き合わせられます。

Claude Platform on AWSでは2つのIDが返る

Claude Platform on AWS経由でAPIを呼んでいる場合、レスポンスにはAWSのリクエストID(x-amzn-requestid)とAnthropicのリクエストID(request-id)の2つが同時に含まれます。用途がはっきり分かれているため、どちらを使うべきかは問い合わせ先で決まります。

AWS環境でこの2つを両方読みたい場合も、raw responseのアクセサーを使う点は共通です。SDKが自動でどちらか一方だけを選んで返すことはないため、実装側でヘッダー名を指定して両方取得します。片方だけを保存してしまうと、CloudTrailの記録とAnthropicサポートのチケットが別々のIDを指す状態になり、後から突き合わせられなくなります。

全呼び出しでrequest-idを記録する実装パターン

サポート問い合わせの場面まで待たず、普段からログにrequest-idを残しておくと、障害発生後の調査が速くなります。Pythonであれば、呼び出しをラップする薄い関数を1つ挟むだけで実現できます。

import logging
 
logger = logging.getLogger("anthropic_client")
 
def create_message(**kwargs):
    message = client.messages.create(**kwargs)
    logger.info("request_id=%s model=%s", message._request_id, kwargs.get("model"))
    return message

TypeScriptでも同じ考え方で、呼び出し箇所を関数に集約してログを1行差し込みます。C#・Go・Java・PHPのようにraw responseアクセサーを使う言語では、ラッパー内でその都度アクセサーへ切り替える必要があるため、通常呼び出しとの分岐がやや増えます。呼び出し全体を1つの窓口に集約しておく設計が、request-idロギングの導入コストを下げます。

req_から始まる値そのものに意味のある構造は無く、Anthropic内部の採番規則に基づく不透明な識別子です。値からリクエスト内容を逆算したり、桁数や文字種を前提にパースしたりする実装は避け、文字列としてそのまま保存・照合する扱いに留めます。

ログに残す際は、リクエストの発生時刻・モデル名とrequest-idを1レコードにまとめておくと、後日サポートへ問い合わせるときに「いつ・どのモデルで・どのIDのリクエストか」をひとつのログ行から即答できます。request-idだけを単独で保存すると、発生日時が分からずログの検索範囲を絞り込めなくなり、結局は総当たりでログを読み返す羽目になります。

よくあるつまずき

エラーオブジェクトのrequest_idとヘッダーのrequest-idを別物だと思い込む。名前のハイフン・アンダースコアの違いに見えますが、値は同じリクエストを指す同一のIDです。ボディから読むかヘッダーから読むかの経路が違うだけです。

Rubyでプロパティアクセスを探して見つからない。Ruby SDKだけは他の6言語と設計が異なり、ミドルウェアという別の仕組みを使います。Python・TypeScriptの感覚でresponse.request_idのようなプロパティを探しても存在しません。

AWS環境でrequest-idだけを保存しCloudTrail調査ができなくなる。Claude Platform on AWSではx-amzn-requestidが主IDです。Anthropicサポート宛の問い合わせにしか使わない前提でrequest-idだけをログに残すと、AWS側の障害調査で参照するIDが手元に無い事態になります。

429や529のたびにrequest-idを添えて問い合わせる。レート制限や過負荷によるエラーは、バックオフを挟んだ再試行やトラフィック調整で解消するのが基本の対処です。公式ドキュメントがrequest-idの利用を明示的に勧めているのは500エラーで、それ以外のステータスまで一律に添付する運用は、原因調査の的を絞りにくくします。

まとめ

request-idはAPIレスポンス全件に付き、成功時はヘッダー、エラー時はボディのrequest_idフィールドからも読めます。SDKごとの取得手段は「プロパティ読み取り」(Python・TypeScript)、「raw responseアクセサー」(C#・Go・Java・PHP)、「ミドルウェア」(Ruby)の3系統に分かれるため、言語を切り替えて実装するときはこの分類を先に把握しておくと迷いません。Claude Platform on AWSを使っている場合は、AWS側のx-amzn-requestidとAnthropic側のrequest-idをどちらもログに残す設計にしておくと、どちらの窓口に問い合わせるときも困りません。エラーコードそのものの分類とリトライ設計はClaude APIのエラーハンドリング設計で扱っています。