Compliance APIのエラー400/403/404の違いと対処法

400は送った値の不正、403はキーにスコープが足りない状態、404は対象が無いか、キーが認証されていない状態です。401はキー自体の不具合で、409はプロジェクトに紐づくチャットが残っているときに返ります。429は取りすぎで、待てば通ります。

同じ404でも「消えた」と「いまは使えない」が混ざる

Compliance APIは標準的なAnthropicのエラー形式で返します。組になるのは、非2xxのステータスコード、request-idレスポンスヘッダー、JSONボディです。ボディにはerror.typeとerror.messageが入ります(Compliance APIとはも参照)。問い合わせ時に添えるのはrequest-idの値です。

厄介なのは、ステータスコードだけではリトライの要否が決まらない点です。チャットの404は「もう存在しない」ですが、ローカルセッションの404の一部は「いまは使えないだけ」を意味します。キーを送り忘れたときも、存在しないパスを叩いたときも、同じ404が返ります。

分岐の軸はHTTPステータスコードとerror.typeです。メッセージ文字列は運用ランブックに転記できる程度に安定していますが、言い回しが変わる可能性があります。ただし、同じステータスと型を共有する一部の応答は、メッセージで見分ける必要があります。該当する箇所は後の節で個別に示します。

ステータス別のリトライ可否

キーの状態で分かれる401・403・404

キーの状態によって、401・403・404のどれが返るかが決まります。

400 Bad Request — 値が受け付けられない

構文は正しくても、サーバーが値を拒否したケースです。メッセージの先頭にパラメータ名が入るので、ログからそのまま原因を引けます。

Compliance APIが有効化されていない

本文はCompliance API is not enabled for this organizationです。キーが有効でも、所属する組織か親組織で機能が有効化されるまで全エンドポイントがこの400を返します。管理者が機能を無効にしたときも同じ応答に戻ります。

未定義のクエリパラメータ

Compliance APIは未定義のパラメータを無視せずに拒否します。メッセージには、近い名前があればその候補が添えられます。

Unknown query parameter: 'created_at[gte]'. Did you mean 'created_at.gte'?

範囲指定はドット記法のcreated_at.gte、配列指定はactivity_types[]のように[]を付けます。ページ送りはafter_id・before_id・pageのどれかで、エンドポイントごとに異なります。

値の検証エラー

limit: Input should be less than or equal to 1000のように、パラメータ名のあとに失敗した制約が続きます。この数値はそのエンドポイントの上限です。上限は一覧ごとに違うため、APIリファレンスのパラメータ制約で確認します。

日時は、UTCオフセット付きのRFC 3339形式(2024-03-01T00:00:00Zなど)で送ります。ローカルセッション一覧は、オフセットのない値に対してcreated_at.gte: Input should have timezone infoを返します。

同じ一覧でcreated_at.ltがcreated_at.gteより後でないときも400です。本文はcreated_at.lt must be strictly after created_at.gte.です。

日時として読めない値には、次のような本文が返ります。

created_at.gte: Input should be a valid datetime or date, invalid character in year

配列の値が許可された値でないときは、activity_types[].0: Input is not one of the permitted values.のように要素の位置が続きます。

セッション本文の切り詰めを制御するtool_use_input_max_bytesとtool_result_max_bytesは、正のバイト数か-1(サーバー上限)だけを受け付けます。0を送ると同じ型の400です。

ページ送りカーソルの不正

カーソルは中身を解釈せず、前回レスポンスの値をそのまま渡します。Activity Feedではafter_id・before_idの値が不正だと400になります。本文は、Invalid activity_id format: 'activity_invalid123'のように送った値を返します。チャット系では、Invalid pagination cursor for 'after_id'のようにパラメータ名が入ります。

組織・ユーザー・ロール・グループ・プロジェクト・セッションの各エンドポイントは、pageトークンでページを送ります。前回のnext_pageを変えずに渡し、has_moreがfalseになったら止めます。セッション系はhas_moreを返さないので、next_pageがnullになったときが終点です。

ローカルセッションの一覧とメッセージ取得は、解読できないpageを400で拒否します。本文はThe page parameter is not a valid cursor for this request.です。保存中に切れた・書き換わったトークン、別のエンドポイントや別の親組織で発行されたトークンが該当します。メッセージ取得では、カーソルが発行元のセッションとorderにひもづくので、別のセッションや並び順での使い回しも同じ400です。

メッセージ取得のカーソルは、ウォークの開始から24時間で失効します。発行から数えるわけではありません。失効したときの本文は次のとおりです。

The page cursor has expired. Restart the walk without a page parameter; results will reflect the current retention boundary.

pageなしでやり直した新しいウォークには、その間に保持期間を過ぎたメッセージは含まれません。

401 Unauthorized — キーの状態が3つの文言に分かれる

401の型はauthentication_errorで、本文は3種類あります。

再有効化の場所は2か所あります。Complianceアクセスキーはclaude.aiの「Organization settings > API」です。Admin APIキーはClaude Consoleの「Settings > Admin keys」です。

401が出た時点で、スコープは調べなくて構いません。

403 Forbidden — 持っているスコープと要るスコープ

403はpermission_error型で、本文にGot:(キーが持つスコープ)とNeeded one of:(受け付けるスコープ)が並びます。これを読めば、ConsoleやClaude.aiを開き直さなくても原因が分かります。

Missing required scopes. Got: ['read:compliance_user_data'] Needed one of: ['read:compliance_org_data', 'read:org_audit']

読み取り系は、列挙されたスコープのどれか1つがあれば通ります。受け付けるリストには、全読み取りエンドポイントを覆うread:org_auditも含まれます。削除系だけはNeeded one of:ではなくNeeded:と1つだけ示されます。

Complianceアクセスキーのスコープは作成後に変更できません。403の対処は、スコープを足した新しいキーの作成になります。各エンドポイントの詳細は組織・ユーザー・ロール・グループ一覧の取得にまとめています。

連携が昨日まで動いていたのに急に403になったときは、廃止済みスコープを疑います。read:compliance_org_settingsは2026年6月30日に廃止され、組織設定エンドポイントはread:compliance_org_dataを要求します。廃止スコープだけを持つキーは、この呼び出しで全件403になります。read:compliance_org_dataを持つキーには影響せず、廃止スコープはキー作成時に選べなくなっています。新しいキーに差し替えたら、古いキーは削除します。

親組織を持たない単独のClaude Console組織は、Complianceアクセスキーを作れません。Activity Feedだけを問い合わせられる形態です。

404 Not Found — 本文で原因が変わる

404は、メッセージの形で原因が分かれます。

名指しのある404は、単純な「不在」です。削除は即時かつ恒久なので、以前取れていたIDの404は、ほとんどの場合、Compliance APIでのハード削除か保持ポリシーによる失効を意味します。チャットが別の組織のものである場合も、同じ404です。ファイルとアーティファクトは、claude.aiでユーザーがチャットを削除したときも、チャットと一緒に消えます。

一方、ユーザーがclaude.aiで削除したチャット自体は404になりません。deleted_atが入った状態で読み取れ、メッセージ本文だけが空になります。「チャットが消えたかどうか」は、404ではなくdeleted_atで見ます。

リソース別の本文と照合先

メッセージはリソースごとに固定の形があり、ログから対象を特定できます。

• チャット: Chat conversation not found: 'claude_chat_...'。claude_chat_createdかclaude_chat_viewedのアクティビティと突き合わせる
• ファイル: File not found: <UUID>。本文にはclaude_file_...ではなく内部のUUIDが入る。チャットごと消えたファイルにはclaude_file_deletedが残らないので、claude_chat_deletedも見る
• 生成ファイル・アーティファクト: 本文は3種類。Generated file not found、Generated file content not found、Artifact version not foundのどれか。チャット側のdeleted_atで消えたかどうかを判断する
• プロジェクト: No project is found with the provided id.。削除エンドポイントは... or it has already been deleted.付きの別本文を返す
• プロジェクトの文書: No project document found with the provided id.。対象はテキスト文書(claude_proj_doc_...)で、プロジェクトのファイルは含まれない

アクティビティ記録のほうは、リソースが消えたあとも残ります。ファイルのバイナリは戻りませんが、アクティビティは6年の保持期間のあいだフィードに残ります。

セッションの404は2種類ある

ローカルセッションのLocal session not found.は、IDが読めるセッションに一致しないときの1本文です。原因は区別されません。別の親組織のID、存在しなかったID、ゼロデータ保持(ZDR)の対象、保持期間を過ぎたセッションのいずれでも同じです。一時的な状態は無いので、一覧に出てこなければ取得不能と見て、IDをキューから外します。

一方のLocal sessions are not available.は、IDに関係なく、一覧を含めて全呼び出しで返ります。顧客側のキー・スコープ・設定では変えられず、一時的なこともあります。両者のerror.typeは同じnot_found_errorなので、見分けにはメッセージを使います。この状態が実行をまたいで続くなら、Anthropicの担当者にrequest-idを添えて連絡します。

リモートセッションのRemote session not found.では、statusがpendingのセッションにメッセージがまだ無く、開始まで404が続きます。一覧でstatusを確認し、pendingを抜けてから再試行します。

組織・ロール・グループと、組織設定の404

組織・ロール・グループのエンドポイントは、メッセージがRole not found.やGroup not found.のように短い形です。組織はorg_uuidが本文に入ります。ロールとグループは削除されることがあり、組織は親ツリーから切り離されることがあります。

組織設定のエンドポイントは別格です。organization ... not found in this organization's hierarchyという本文で、3つの原因が同じ応答になります。親組織にひもづかない組織ID、UUID形式でない値、親組織でまだ有効化されていない設定エンドポイントです。組織IDの実在を応答から推測させない意図の設計です。実在が分かっているIDでも404なら、担当者に有効化を問い合わせます。

409 Conflict — 子を先に外す

409は、プロジェクトにチャットが紐づいたまま削除したときに返ります。型はconflict_errorではなくinvalid_request_errorです。400と同じ型なので、error.typeではなくステータスコードで見分けます。

対処は、チャットの削除か切り離しを先に済ませることです。手順は次のとおりです。

429 Too Many Requests — 予算は2種類ある

レート制限は、親組織あたり毎分600リクエストです。Complianceアクセスキーと連結組織すべてのAdmin APIキーが、/v1/compliance/*の全エンドポイントで1つの枠を分け合います。単独のClaude Console組織は、組織自身に同じ枠が掛かり、Admin APIキーで共有されます。

HTTP/1.1 429 Too Many Requests
retry-after: 25
anthropic-ratelimit-requests-limit: 600
anthropic-ratelimit-requests-remaining: 0
anthropic-ratelimit-requests-reset: 2026-04-21T14:38:25Z

429のとき、ページネーションのカーソルは進めません。失敗したリクエストはデータを返していないので、最後に成功したページのカーソルが次回もそのまま正しい値です。429の本文は次の文で始まります。

Compliance API rate limit of 600 requests per minute per parent organization has been exceeded.

続けて、retry-afterの時刻まで待つことと、問い合わせにrequest-idを添えることが案内されます。retry-afterはanthropic-ratelimit-requests-resetに少し余裕を足した値のことがあるため、待つ時間はretry-afterを優先します。

retry-afterが中継で落ちていたら、1秒から始めて最大60秒まで倍にするバックオフで代用します。

認証に失敗したリクエストはレート制限の手前で弾かれ、クォータを消費しません。スコープ不足の403だけは、1クォータを使ってから返ります。Activity Feedを定期的に読む場合は、全キー・連結組織・並列ワーカーの合計が600を下回るよう、呼び出し頻度を設計します。

500 / 502 / 503 / 504 / 529 — ヘッダーと本文で分ける

500にx-should-retry: falseが付いていれば、決定論的な失敗です。何度再送しても同じ結果になります。Claude SDKはこのヘッダーに自動で従いますが、5xxを無条件に再試行する汎用ライブラリでは、止める設定を自分で入れます。

ヘッダーのない500と、502・503・504・529は一時的です。同じバックオフで再送します。

ローカルセッションの503は、一時的とは限らない

型はすべてoverloaded_errorで、本文は3種類です。

顧客管理鍵(customer-managed encryption key)を使う組織では、メッセージ取得で、鍵が復号できない内容を含むページごとにCaptured contentが返ります。鍵を無効化・失効・破棄した場合や、鍵に到達できない場合です。本文は一時的な不調と同じなので、同じ組織で繰り返し出ることだけが手がかりになります。鍵が使えない状態でnot_capturedと報告されることはありません。

その組織のトランスクリプトの巡回は、いったん止めます。他の連結組織のトランスクリプトと、全組織のセッションメタデータは影響を受けません。後日の実行で再試行するときは、メッセージ取得のカーソルが24時間で失効しているため、pageなしでウォークをやり直します。

一時的な不調が繰り返し続くなら、Anthropicの担当者にrequest-idを添えて連絡します。顧客管理鍵の場合は、鍵が使える状態で続くときに限ります。

retention overridesの本文は、取得とメッセージ取得ではfor this pageがfor this sessionになります。一覧では、pageを外して最初から読み直すか、created_at.gteとcreated_at.ltの窓を狭めて成功させ、飛ばした範囲を後続の実行で別に取ります。24時間を過ぎた一覧のpageトークンも受け付けられますが、現在の保持境界で再評価されるため、止めていた巡回がセッションを取りこぼすことがあります。取得とメッセージ取得では、そのセッションIDを飛ばして残りを進め、後続の実行でやり直します。

応答の判定順と、カーソル・IDの扱い

メッセージ本文まで見る必要があるのは、400の中身の判別、401の3文言、裸のNot foundと名指しの404、ローカルセッションの404・503です。それ以外はerror.typeかステータスで足ります。409は400と同じinvalid_request_errorなので、ステータスで判定します。

エンドポイントの有効化とスコープ設計はCompliance APIのFAQにまとめています。

まとめ

エラーの再試行は、ステータスだけでなく、404とローカルセッションの503では本文まで見て決めます。あわせて、再試行しない応答では対象のIDをキューから外し、429と503ではカーソルを進めないことが、巡回を止めずに続けるための判断軸になります。