處理 Compliance API 錯誤

本頁依 HTTP 狀態碼列出常見的 Compliance API 錯誤回應，並說明每個錯誤的原因與修正方式。

Compliance API 以標準的 Anthropic 錯誤格式回傳錯誤：一個非 2xx 的狀態碼、一個 request-id 回應標頭，以及一個 JSON 主體，其中的 error 物件包含 type 與 message。當您向支援團隊提報問題時，請附上 request-id 標頭的值。

{
  "error": {
    "type": "permission_error",
    "message": "Missing required scopes. Got: ['read:compliance_activities'] Needed one of: ['read:compliance_user_data', 'read:org_audit']"
  }
}

在本頁中，本機工作階段（local sessions）在使用者的機器上執行，遠端工作階段（remote sessions）則在雲端執行；請參閱擷取工作階段逐字稿。

請依據 HTTP 狀態碼與 error.type 進行比對，而非訊息字串。訊息足夠穩定，可以複製到操作手冊中，但可能會隨時間改寫；狀態碼與 type 值則屬於 API 合約的一部分。少數共用相同狀態碼與 type 的回應，若回應中帶有 error.details.error_code 錯誤代碼，則以該代碼區分，否則以其訊息區分；每種情況都會在適用之處特別說明。

下表讓您一眼就能判斷是否應重試。後續各節會顯示逐字的錯誤主體與修正方式。

400 Bad Request

請求在語法上有效，但伺服器拒絕了某個參數，或該組織未啟用 Compliance API。請修正訊息中指出的原因並重新傳送。有一種 400 不同：記錄頁面過大，即使每個參數都有效，本機工作階段訊息端點仍可能針對非常大的工作階段的某一頁傳回此錯誤；該項目說明了應改採的做法，而非重新傳送。

未啟用 Compliance API

Type： invalid_request_error

Compliance API is not enabled for this organization

原因： 金鑰有效，但該金鑰所屬的組織或上層組織未啟用 Compliance API。在 API 啟用之前，每個端點都會傳回此回應；若管理員關閉 API，也會再次傳回此回應。

修正方式： 依照設定 Compliance API 啟用 Compliance API，然後重新傳送請求。

未知的查詢參數

類型： invalid_request_error

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

原因： 請求包含端點未定義的查詢參數；Compliance API 會拒絕無法辨識的參數，而非忽略它們。訊息會指出該參數名稱，並且對於相近的錯誤（例如以方括號表示法取代點號，或缺少 [] 後綴），會建議已定義的名稱。

修正方式： 使用端點的 Compliance API 參考頁面上所列的參數名稱。範圍篩選器使用點號表示法（例如 created_at.gte），陣列篩選器需加上 [] 後綴（例如 activity_types[]），而分頁參數則依端點而定，為 after_id、before_id 或 page。

無效的參數值

類型： invalid_request_error

limit: Input should be less than or equal to 1000

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.

原因： 某個查詢參數的值未通過驗證。訊息以參數名稱開頭（若為陣列參數，後面會接著元素的位置），接著說明未通過的限制條件。此處列出三種常見情況：limit 超過端點的上限（訊息中的數字即為該端點的上限）、created_at.* 或 updated_at.* 的值無法解析為日期或時間戳記，以及 activity_types[] 的值不是受支援的活動類型。

修正方式： 修正訊息中指出的參數。每個列表端點都有各自的 limit 範圍；請參閱對應的 Compliance API 參考頁面上的參數限制。請以 RFC 3339 格式並附上明確的 UTC 偏移量傳送時間戳記，例如 2024-03-01T00:00:00Z 或 2024-03-01T00:00:00+00:00；本機工作階段列表會拒絕沒有偏移量的時間戳記（created_at.gte: Input should have timezone info）。關於受支援的 activity_types[] 值，請參閱查詢合規活動。

本機工作階段列表（GET /v1/compliance/apps/sessions/local）在您提供下限（created_at.gte 或 created_at.gt）與上限（created_at.lt 或 created_at.lte）且上限並未晚於下限時，也會回傳 400 invalid_request_error。只有 created_at.gte 搭配 created_at.lte 時才允許上下限相等。訊息會指出這兩個參數，例如：

created_at.lt must be strictly after created_at.gte.

created_at.lte must be at or after created_at.gte.

請送出晚於下限的上限，或省略其中一個界限。

工作階段記錄端點（GET /v1/compliance/apps/sessions/local/{session_id}/messages 與 GET /v1/compliance/apps/sessions/remote/{session_id}/messages）也以相同方式驗證其截斷參數：tool_use_input_max_bytes 與 tool_result_max_bytes 各自接受正數的位元組數或 -1（伺服器上限），因此像 0 這樣的值會傳回相同的 400 invalid_request_error。

無效的分頁游標

Type： invalid_request_error

Invalid activity_id format: 'activity_invalid123'

Invalid pagination cursor for 'after_id'

原因： 「pagination cursor」（分頁游標）無法解碼。在 Activity Feed 上，若 after_id 或 before_id 的值既不是 API 發出的游標，也不是格式正確的活動 ID，會傳回第一個主體，其中會回顯所傳送的值。在聊天與聊天訊息端點上，若 after_id 或 before_id 的值無法解碼，會傳回第二個主體，其中會指出該參數名稱。

修正： 將分頁游標視為不透明字串。請一律複製上一頁回傳的 first_id 或 last_id 值；當 has_more 為 false 時停止。不要從物件 ID 自行建構游標。

目錄、專案與工作階段端點（組織、使用者、角色、角色權限、群組、群組成員、專案、專案附件、本機與遠端工作階段，以及工作階段訊息）使用不透明的 page 權杖進行分頁，而非 after_id 與 before_id。相同的建議同樣適用：原封不動地傳遞上一個回應中的 next_page 值，並在 has_more 為 false 時停止（或者，在不傳回 has_more 的工作階段端點上，於 next_page 為 null 時停止）。格式錯誤的 page 權杖會傳回與格式錯誤的 after_id 或 before_id 相同的 400 invalid_request_error，但訊息會因端點而異。

兩個分頁式的本機工作階段端點（列表與 messages 端點）對於任何無法解碼的 page 值都會回傳下列 400 invalid_request_error，例如在您儲存後遭截斷或竄改的權杖，或由不同端點或在不同上層組織下核發的權杖。在本機工作階段 messages 端點（GET /v1/compliance/apps/sessions/local/{session_id}/messages）上，每個 page 游標也綁定於其核發時所對應的工作階段與 order，因此為不同工作階段或排序順序核發的游標會回傳相同的主體：

The page parameter is not a valid cursor for this request.

messages 端點上的游標也會在走訪（walk，即完整翻過所有頁面一次）開始後 24 小時過期。過期的游標會回傳：

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

對於第一個主體，請將上一個回應中未經修改的 next_page 值重新送至核發它的端點與工作階段。對於過期的游標，請在不帶 page 參數的情況下重新開始；新的走訪會反映其開始時生效的保留界限，因此在此期間已超出保留期限的訊息將不再回傳（請參閱擷取本機工作階段逐字稿）。

記錄頁面過大

Type： invalid_request_error

錯誤代碼： transcript_page_read_limit_exceeded，於 error.details.error_code 中傳回

This page of the session's transcript is too large to read, and retrying will not help. If you are reading newest first (order=desc), read this session oldest first instead: omit the order and page parameters, then follow next_page.

原因： GET /v1/compliance/apps/sessions/local/{session_id}/messages 可能會針對非常大的工作階段的某一頁傳回此錯誤。只有此端點會傳回此錯誤。它與其他 400 共用 invalid_request_error type，因此請以其錯誤代碼識別，而非以可能被改寫的訊息文字識別。

修正： 請勿重試該請求。如果請求使用了 order=desc，請改為從最舊的開始讀取該工作階段：

• 在不帶 order（或使用 order=asc）且不帶 page 的情況下，重新開始該工作階段的走訪（對其各頁面的一次完整瀏覽；請參閱擷取本機工作階段對話記錄），並持續追蹤 next_page 直到其為 null。您已從最新優先讀取中儲存的訊息會保有相同的 id，因此請依 id 去除重複。
• 為此次走訪將您用戶端的請求逾時設定為至少 5 分鐘。
• 降低 limit 並不是避免此錯誤的可靠方法。

如果最舊優先的請求傳回此錯誤，也請勿重試。保留您已讀取的頁面，將該工作階段記錄為不完整，繼續匯出其餘內容，並附上 request-id 回應標頭聯絡您的 Anthropic 代表。

401 Unauthorized

請求攜帶的 Compliance Access Key（sk-ant-api01-...）或 Admin API 金鑰（sk-ant-admin01-...）未通過驗證。未攜帶金鑰或攜帶其他類型金鑰的請求，在除了組織設定以外的所有端點上，都會改為傳回 404 Not Found；而範圍錯誤的有效金鑰則會傳回 403 Forbidden。

無效、已停用或已過期的 API 金鑰

Type： authentication_error

API key is invalid.

API key has been deactivated.

API key has expired.

原因： API key is invalid. 表示所傳送的值與任何可用的金鑰都不相符，例如在儲存時遭到截斷或修改。API key has been deactivated. 表示該金鑰已被停用或刪除。API key has expired. 表示 Admin API 金鑰的到期日已過；Compliance Access Key 在建立時不會設定到期日。

修正： 對於 API key is invalid.，請將用戶端傳送的值與建立金鑰時您所儲存的密鑰進行比對；完整密鑰只會顯示一次，因此如果您儲存的副本有誤，請建立新的金鑰。對於 API key has been deactivated.，如果金鑰只是被停用，請重新啟用：Compliance Access Key 請至 claude.ai > Organization settings > API，Admin API 金鑰則請至 Claude Console 中的 Admin keys 頁面（platform.claude.com/settings/admin-keys）；已刪除的金鑰無法復原。對於已刪除或已過期的金鑰，請建立新的金鑰並更新您的整合以使用它，如管理與輪替金鑰所述。

403 Forbidden

x-api-key 中的金鑰有效，但未攜帶端點所接受的範圍。逐字訊息會列出金鑰所攜帶的範圍（Got:）以及端點所接受的範圍（讀取端點上為 Needed one of:，列出的任一範圍即已足夠；刪除端點上則為 Needed:），因此您無需重新檢查 Claude Console 或 claude.ai，即可確認金鑰攜帶了哪些範圍。在讀取端點上，接受的清單還包括 read:org_audit，這是一個涵蓋所有 Compliance API 讀取端點的唯讀稽核範圍；請參閱為 Claude Enterprise 金鑰選擇範圍。Compliance Access Key 的範圍在建立後即無法變更，因此每個範圍不足的修正方式都會引導您建立新的金鑰，而非編輯現有金鑰。獨立的 Claude Console 組織（沒有上層組織的組織）無法建立 Compliance Access Key，因此需要此類金鑰的修正方式不適用於它；它只能查詢 Activity Feed。

Scope 不足：Activity Feed

Type： permission_error

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

原因： 使用了不具 read:compliance_activities 的金鑰呼叫 GET /v1/compliance/activities。導致此錯誤的常見途徑有兩種：

• Compliance Access Key（sk-ant-api01-...）在建立時未包含 read:compliance_activities scope。
• Claude Console Admin API 金鑰（sk-ant-admin01-...）是在組織尚未啟用 Compliance API 時建立的。在 Compliance API 未啟用時建立的金鑰不具備該 scope；請參閱設定 Compliance API。

修正： Compliance Access Key 的 scope 在建立後不可變更。請建立包含 read:compliance_activities 的新金鑰，或使用 Claude Console Admin API 金鑰。請參閱您需要哪種金鑰？以了解 Admin API 金鑰在何種條件下具備此 scope。

Scope 不足：組織資料

Type： permission_error

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

原因： 使用了不具 read:compliance_org_data 的金鑰呼叫組織、角色、群組或有效設定端點。導致此錯誤的常見途徑有兩種：

• Compliance Access Key（sk-ant-api01-...）在建立時未包含 read:compliance_org_data scope。
• 使用了 Claude Console Admin API 金鑰（sk-ant-admin01-...）。Admin API 金鑰僅具備 read:compliance_activities，無法讀取組織中繼資料。

修正： 建立新的 Compliance Access Key，並勾選 read:compliance_org_data。Admin API 金鑰無法讀取組織中繼資料；必須使用 Compliance Access Key。

已淘汰的 scope：組織設定

Type： permission_error

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

原因： read:compliance_org_settings scope 已於 2026 年 6 月 30 日淘汰。GET /v1/compliance/organizations/{organization_id}/settings 現在需要 read:compliance_org_data，與其他組織端點相同的 scope，而已淘汰的 scope 不再授權任何操作。僅具備 read:compliance_org_settings 的 Compliance Access Key 在每次呼叫設定端點時都會回傳此錯誤，即使該金鑰在淘汰前可正常運作。建立金鑰時已無法再選取或授予已淘汰的 scope。

修正： Compliance Access Key 的 scope 在建立後不可變更。請建立新的 Compliance Access Key 並勾選 read:compliance_org_data，更新您的整合以使用它，然後刪除舊金鑰。已具備 read:compliance_org_data 的金鑰不受此淘汰影響。

Scope 不足：使用者資料

Type： permission_error

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

原因： 使用了不具 read:compliance_user_data 的金鑰呼叫聊天、訊息、檔案、專案、工作階段、組織使用者或群組成員端點。導致此錯誤的常見途徑有兩種：

• Compliance Access Key（sk-ant-api01-...）在建立時未包含 read:compliance_user_data scope。
• 使用了 Claude Console Admin API 金鑰（sk-ant-admin01-...）。Admin API 金鑰僅具備 read:compliance_activities，且無法被授予 read:compliance_user_data，因此無法呼叫聊天、檔案、專案、專案附件、工作階段、使用者或群組成員端點。

修正： 使用在 claude.ai 中建立並勾選 read:compliance_user_data 的 Compliance Access Key。如果該請求確實應僅限於 Activity Feed，請改將 Admin API 金鑰指向 GET /v1/compliance/activities。

Scope 不足：刪除

Type： permission_error

Missing required scopes. Got: ['read:compliance_user_data'] Needed: ['delete:compliance_user_data']

原因： 使用了不具 delete:compliance_user_data 的 Compliance Access Key 呼叫聊天、檔案或專案的 DELETE 端點。

修正： 建立新的 Compliance Access Key 並勾選 delete:compliance_user_data。刪除 scope 與 read:compliance_user_data 分開，以確保唯讀稽核金鑰無法刪除內容。

404 Not Found

若 404 的訊息指名某個資源或資源類型，表示路徑中的 ID 不存在或已被刪除。Compliance API 的刪除是立即且永久的，因此對先前已知的 ID 傳回 404，通常表示內容已消失：透過 Compliance API 刪除呼叫被永久刪除、被保留政策移除，或者（對於檔案與成品而言）隨著使用者在 claude.ai 中刪除其聊天而一併被刪除。訊息僅為 Not found 的 404 則不同：請求未通過驗證（或路徑不存在），任何端點都可能傳回此錯誤，包括列表端點；請參閱請求未通過驗證。工作階段端點另有兩種情況。在本機工作階段端點上，當這些端點無法供您的上層組織使用時，每次呼叫（包括列表）都會傳回另一個 404 訊息 Local sessions are not available.；此訊息與工作階段 ID 無關，且可能是暫時性的。請參閱找不到本機工作階段。在遠端工作階段端點上，仍在佈建中的工作階段（status 為 pending）尚無記錄，因此其訊息端點在工作階段啟動前會傳回 404。請參閱找不到遠端工作階段。各修正方式中引用的活動類型字串（例如 claude_chat_created）是您可以傳遞給 Activity Feed activity_types[] 篩選器的值；所有受支援的值請參閱查詢合規活動。

請求未通過驗證

類型： not_found_error

Not found

原因： 請求未攜帶 Compliance API 接受的憑證：未傳送 API 金鑰，或金鑰不是 Compliance Access Key（sk-ant-api01-...）或 Admin API 金鑰（sk-ant-admin01-...），例如 Claude API 金鑰（sk-ant-api03-...）。其狀態、類型與訊息與不存在的路徑相同，且與端點或任何資源 ID 無關，因此像 GET /v1/compliance/activities 這樣的列表端點也會傳回此主體。唯一的例外是 GET /v1/compliance/organizations/{organization_id}/settings，它會以 401 authentication_error 回應這類請求。在所有端點上，未通過驗證的 Compliance Access Key 或 Admin API 金鑰則會改為傳回 401 Unauthorized。

修正方式： 在 x-api-key 標頭中傳送金鑰並檢查其前綴：Compliance API 只接受 sk-ant-api01-... 與 sk-ant-admin01-... 金鑰；請參閱您需要哪種金鑰？。如果標頭與金鑰都正確，但某個路徑仍傳回 Not found 而其他路徑成功，請對照 Compliance API 參考檢查該路徑。

找不到聊天

Type： not_found_error

Chat conversation not found: 'claude_chat_01H5CWunD7RpVJ5bHa8RCkja'

原因： 路徑中的聊天 ID 與可透過 Compliance API 讀取的聊天不符。該聊天可能已透過先前的 Compliance API 呼叫被硬刪除，或被您組織的保留政策移除，或者它可能屬於呼叫金鑰無法讀取的組織。使用者在 claude.ai 中刪除的聊天不會回傳 404；它們仍可讀取，deleted_at 會被填入，但不含其訊息內容。

修正： 對照最近的 claude_chat_created 或 claude_chat_viewed 活動確認聊天 ID。如果活動是最近的而讀取仍然失敗，則該聊天已被硬刪除（透過此 API 或因保留政策到期），或屬於您金鑰範圍之外的組織。

找不到檔案

Type： not_found_error

File not found: 0d3b8f72-6c1e-4a59-b2de-7f4c9a1e5b60

原因： 該檔案 ID 不存在於您金鑰可讀取的組織中，或該檔案已被刪除。在 claude.ai 中刪除聊天也會刪除附加於其上的檔案，但聊天本身仍會列出。訊息會以底層 UUID 識別檔案，而非請求中傳送的 claude_file_... ID。中繼資料、內容與刪除端點會傳回此主體；它同時適用於附加於聊天的檔案（claude_file_...）與專案檔案。

修正方式： 對照最近的 claude_file_uploaded 或 claude_file_deleted 活動進行核對。隨聊天一併刪除的檔案沒有 claude_file_deleted 活動，因此也請檢查該聊天的 claude_chat_deleted 活動。如果檔案已被刪除，其二進位內容便已消失；活動記錄則會在 6 年的保留期間內保留在動態中。

找不到產生的檔案或成品

類型： not_found_error

Generated file not found: 'claude_gen_file_01TbR8wAcCeFhJkLnPqStUvX'

Generated file content not found: 'claude_gen_file_01TbR8wAcCeFhJkLnPqStUvX'

Artifact version not found: 'claude_artifact_version_01KmNpQrSt3UvWxYz5AbCdEfG'

原因： 路徑中的 ID 與任何可透過 Compliance API 讀取的工具產生檔案或成品版本都不相符。產生檔案的中繼資料端點會傳回第一個主體，內容端點會傳回第二個主體，而兩個成品端點都會傳回第三個主體。產生的檔案與成品會隨著建立它們的聊天一併刪除，包括使用者在 claude.ai 中刪除該聊天的情況。

修正方式： 使用取得聊天訊息查詢該 ID 所屬的聊天。如果該聊天的 deleted_at 有值，或有 claude_chat_deleted 活動指名該聊天，表示內容已消失；請將該 ID 從您的佇列中移除。否則，請對照該聊天訊息上的 generated_files 與 artifacts 陣列確認 ID。

找不到專案

Type： not_found_error

No project is found with the provided id.

No project found with provided id, or it has already been deleted.

原因： 該專案 ID 不存在或已被刪除。專案詳細資料、附件與協作者端點會傳回第一個主體；DELETE /v1/compliance/apps/projects/{project_id} 會傳回第二個主體。

修正： 對照最近的 claude_project_created 或 claude_project_deleted 活動進行核對。即使專案本身已消失，Activity Feed 仍會持續公開該專案的生命週期事件。

找不到專案文件

Type： not_found_error

No project document found with the provided id.

No project document found with the provided id, or it has already been deleted.

原因： 該專案文件 ID 不存在或已被刪除。文件內容與中繼資料端點會傳回第一個主體；DELETE /v1/compliance/apps/projects/documents/{document_id} 會傳回第二個主體。此錯誤適用於文字專案文件（claude_proj_doc_...），而非專案檔案。

修正方式： 使用 GET /v1/compliance/apps/projects/{project_id}/attachments 列出目前的附件。如果文件不在其中，表示它已被刪除；若您只需要中繼資料，可透過 claude_project_document_uploaded 活動記錄取得。活動記錄會顯示上傳文件的人員、時間以及上傳至哪個專案，但不包含文件名稱。

找不到本機工作階段

Type： not_found_error

Local session not found.

原因： 傳入 GET /v1/compliance/apps/sessions/local/{session_id} 或 GET /v1/compliance/apps/sessions/local/{session_id}/messages 的工作階段 ID 與可透過 Compliance API 讀取的本機工作階段不符。在下列情況下，兩個端點都會回傳這同一則訊息而不區分原因：該 ID 不是您金鑰可讀取之組織中的工作階段（包括屬於另一個上層組織的 ID）、該工作階段從未存在、該工作階段適用零資料保留，或該工作階段的所有活動皆已超過適用於執行它之組織的保留期限。Local session not found. 回應沒有暫時性形式，因為本機工作階段沒有佈建（pending）狀態；請對照找不到遠端工作階段，其中 pending 工作階段在啟動前會回傳 404。格式不正確的 clls_ 識別碼工作階段 ID 則會回傳 400 Bad Request。

當本機工作階段端點本身對您的上層組織不可用時，這些端點（包括列表端點）會回傳另一則 404 訊息 Local sessions are not available.。該回應與工作階段 ID 無關；客戶端的任何金鑰、scope 或設定都無法改變它，且它可能是暫時性的。兩種回應都帶有 not_found_error type；區分它們的是訊息文字。

修正： 對照 GET /v1/compliance/apps/sessions/local 確認工作階段 ID；請參閱使用者機器上的工作階段。如果該工作階段不再出現在列表中，表示其內容已超過保留期限（或該工作階段因其他原因不再位於您金鑰可讀取的組織中），其逐字稿無法擷取；請將該 ID 從您的佇列中移除。如果每次呼叫（包括列表）都回傳 Local sessions are not available.，請保留您佇列中的工作階段 ID，並在下一次排程執行時重試；如果該回應持續出現，請聯絡您的 Anthropic 代表並附上 request-id 回應標頭。

找不到遠端工作階段

Type： not_found_error

Remote session not found.

原因： 傳入 GET /v1/compliance/apps/sessions/remote/{session_id}/messages 的工作階段 ID 與可透過 Compliance API 讀取的工作階段逐字稿不符。這會發生在工作階段 ID（cse_...）不存在或工作階段已被刪除時、工作階段屬於您金鑰無法讀取的組織時，或工作階段的 status 仍為 pending 時：pending 工作階段尚無逐字稿，因此 messages 端點在工作階段啟動前會回傳 404。格式不正確的 cse_ 識別碼工作階段 ID 則會回傳 400 Bad Request。

修正： 對照 GET /v1/compliance/apps/sessions/remote 確認工作階段 ID 及其 status；請參閱雲端中的工作階段。如果工作階段為 pending，請在它離開該狀態後重試。如果該工作階段不再出現在列表中，表示它已被刪除，其逐字稿無法擷取。

找不到組織、角色或群組

Type： not_found_error

The "ce86b5f3-7c16-48b3-a9f3-e1d2c4b8a0f1" organization does not exist or the requester is not authorized to access it.

組織、角色與群組端點以標準錯誤格式回傳 404 not_found_error。組織訊息會指出 org_uuid；角色與群組訊息則為通用訊息（Role not found.、Group not found.）。這會發生在路徑 ID（org_uuid、role_id 或 group_id）不存在，或不再屬於呼叫金鑰可讀取的樹狀結構時。

原因： 路徑中的 ID 與可透過 Compliance API 讀取的記錄不符。角色與群組可以被刪除，組織也可以從上層樹狀結構中取消連結。

修正： 對照對應的列表端點驗證 ID，並對照 Activity Feed 中最近的組織、角色或群組活動進行核對。

組織設定不可用

Type： not_found_error

organization `91012d09-e48b-438e-a489-1bebfd8fa6f9` not found in this organization's hierarchy

原因： GET /v1/compliance/organizations/{organization_id}/settings 在三種情況下回傳此 404，這三種情況刻意共用相同的主體，使回應不會揭露組織是否存在：organization_id 不是您上層組織的已連結組織之一、該值不是有效的 UUID，或設定端點尚未為您的上層組織啟用。

修正： 對照列出組織驗證 ID。如果已知正確的組織 ID 仍回傳 404，表示設定端點尚未為您的上層組織啟用；請聯絡您的 Anthropic 代表。

409 Conflict

請求格式正確且已獲授權，但與資源的目前狀態衝突。主體帶有 invalid_request_error 類型，400 回應也使用此類型，因此請透過 409 狀態碼而非 error.type 來辨別衝突。

專案有附加的聊天

類型： invalid_request_error

The "claude_proj_01KGp4eZNug9ri4kE35RSppq" project cannot be deleted as it has chats attached to it. Delete or detach all chats, and try deleting the project again.

原因： 對仍有聊天附加的專案呼叫了 DELETE /v1/compliance/apps/projects/{project_id}。

修正： 使用 GET /v1/compliance/apps/chats?user_ids[]={user_id}&project_ids[]={project_id} 列出專案的聊天（project_ids[] 篩選器需要至少一個 user_ids[] 值；請透過列出組織使用者列舉 ID），使用 DELETE /v1/compliance/apps/chats/{claude_chat_id} 逐一刪除，然後重試專案刪除。

429 Too Many Requests

對 Compliance API 的請求限制為每個上層組織每分鐘 600 個請求。此限制是上層組織下所有金鑰（Compliance Access Keys 以及所有已連結組織的 Admin API 金鑰）與所有 /v1/compliance/* 端點共用的單一額度；遠端工作階段端點在此之上另有第二個請求額度。對於沒有上層組織的獨立 Claude Console 組織，相同的額度適用於該組織本身，並由其 Admin API 金鑰共用。如果您的整合需要更高的限制，請聯絡您的 Anthropic 代表。

有一種 429 不同：在非常大的工作階段上，本機工作階段訊息端點可能會傳回伺服器忙於讀取大型對話記錄，這既不是速率限制，也不是對您組織的限制。本節末尾的相關條目說明了如何識別它以及該如何處理。

一旦您的 API 金鑰通過驗證，Compliance API 回應會透過標準的速率限制回應標頭回報共用額度，讓您的用戶端可以主動節流，而非等待 429：

• anthropic-ratelimit-requests-limit 是每分鐘的請求額度。
• anthropic-ratelimit-requests-remaining 是目前視窗中剩餘的額度。
• anthropic-ratelimit-requests-reset 是視窗重設並恢復完整額度時的 RFC 3339 時間戳記。

429 回應也帶有 retry-after 標頭，其中包含送出下一個請求前應等待的秒數。此值可能包含超出 anthropic-ratelimit-requests-reset 的少量安全餘裕；請遵循 retry-after。

HTTP/1.1 429 Too Many Requests
date: Tue, 21 Apr 2026 14:38:02 GMT
retry-after: 25
anthropic-ratelimit-requests-limit: 600
anthropic-ratelimit-requests-remaining: 0
anthropic-ratelimit-requests-reset: 2026-04-21T14:38:25Z

{
  "error": {
    "type": "rate_limit_error",
    "message": "Compliance API rate limit of 600 requests per minute per parent organization has been exceeded. Retry after the time indicated by the retry-after header. Quote the request-id response header when contacting Anthropic support."
  }
}

原因： 您的上層組織（或獨立 Claude Console 組織）在 1 分鐘視窗內，跨所有共用其額度的金鑰，向 /v1/compliance/* 送出了超過 600 個請求，或者耗盡了遠端工作階段端點的第二個請求額度（本節稍後說明）。

修正： 等待 retry-after 標頭中的秒數後重試。如果該標頭不存在（例如被中介移除），請退回使用指數退避（從 1 秒開始，加倍至最多 60 秒）。遇到 429 時不要推進您的分頁游標：失敗的請求未回傳任何資料，因此上一個成功頁面的游標仍然正確。

驗證失敗的請求（缺少或無法辨識的金鑰，或使用 Claude API 金鑰而非 Compliance Access Key 或 Admin API 金鑰）會在速率限制器之前被拒絕，不會消耗配額。缺少端點所需 scope 的有效金鑰會在回傳 403 之前消耗一個配額單位。

本機工作階段端點僅計入共用限制。遠端工作階段端點則在共用限制之上另有第二個請求額度，與共用限制一樣以您的上層組織為單位。來自該額度的 429 所帶的 retry-after 標頭一律為 1（最短等待時間，而非實際重設時間）；該回應上的任何 anthropic-ratelimit-* 標頭描述的是共用限制而非此額度，因此如果 429 重複出現，請使用指數退避。有一種 429 並非來自任何請求額度：伺服器忙於讀取大型對話記錄，僅由本機工作階段訊息端點傳回。

如果您依排程輪詢 Activity Feed，請將您的總請求速率（跨所有金鑰、已連結組織與並行工作者）控制在共用限制以下。請觀察 anthropic-ratelimit-requests-remaining，在達到限制前放慢速度。請參閱設計您的合規整合，以了解如何在視窗輪詢與游標驅動擷取之間做選擇。

伺服器忙於讀取大型對話記錄

類型： rate_limit_error

錯誤代碼： transcript_read_server_busy，於 error.details.error_code 中傳回

Too many large session transcripts are being read at once. This is not a limit on your organization. Retry this request after the number of seconds in the retry-after header.

原因： GET /v1/compliance/apps/sessions/local/{session_id}/messages 可能會針對非常大的工作階段的某一頁傳回此 429。只有此端點會傳回此錯誤，且無論 order 值為何都可能發生。這既不是速率限制，也不是對您組織的限制：它並不表示您超過了共用限制或任何其他請求額度。此錯誤與速率限制回應共用 429 狀態碼和 rate_limit_error 類型，因此請透過其錯誤代碼來識別，而非訊息文字，因為訊息文字可能會被改寫。

修正方式：等待 retry-after 標頭中的秒數，然後原封不動地再次傳送相同的請求：保留相同的 page 值，如果原請求沒有該值則同樣不帶。如果重試再次傳回此錯誤，請以相同方式等待並重試。如果 retry-after 標頭不存在，請改用指數退避（從 1 秒開始，每次加倍，最多 60 秒）。如果此錯誤在多次執行中持續出現，請聯繫您的 Anthropic 代表，並附上 request-id 回應標頭。

500 Internal Server Error

當失敗屬於確定性失敗時，來自 Compliance API 的 500 會帶有 x-should-retry: false 回應標頭。Claude SDK 會自動遵循此標頭。如果您使用會對每個 5xx 進行重試的通用 HTTP 重試函式庫，請在 x-should-retry 為 false 時停止重試；重試此錯誤每次都會以相同方式失敗。

不帶 x-should-retry: false 標頭的 500 是暫時性的：請以指數退避重試（從 1 秒開始，加倍至最多 60 秒）。502、503、504 與 529 回應也適用相同做法。例外是接下來說明的一小組本機工作階段 503，它們取決於組織的設定或加密金鑰，而非負載。請參閱錯誤以了解全平台的重試語意。

本機工作階段暫時不可用

Type： overloaded_error

The local-sessions index is temporarily unavailable. Try again shortly.

Captured content is temporarily unavailable. Try again shortly.

The local-sessions index cannot currently evaluate retention overrides for this page. Try again later.

原因： 本機工作階段端點會以這些主體之一回傳 503。三者共用 overloaded_error type，因此這是本頁少數需要依訊息文字而非 error.type 來區分情況的錯誤之一：

• index is temporarily unavailable 回應主體表示工作階段清單因負載或後端狀況而暫時無法使用。這是暫時性的。
• Captured content 回應主體表示目前無法傳回某個工作階段的對話記錄內容。這通常也是暫時性的。在使用客戶管理的加密金鑰的組織中，對於任何包含您的客戶管理金鑰無法解密之內容的頁面，messages 端點也會傳回此回應主體，例如因為您已停用、撤銷或銷毀該金鑰，或因為無法連線至該金鑰。在這種情況下，只要該金鑰無法使用，此錯誤就會持續存在。無論哪種情況，訊息文字都相同，因此判斷原因出在金鑰的唯一依據，是該錯誤在該組織中持續重複發生。無法使用的金鑰絕不會被回報為 not_captured。
• retention overrides 回應主體表示套用於所請求範圍內一個或多個工作階段的保留或資料處理設定尚無法評估。在 retrieve 和 messages 端點上，其內容會顯示為 for this session，而非 for this page。此狀況取決於執行該工作階段之組織的資料與設定，而非負載，且可能會持續一段較長的時間。

修正： 請依下列方式處理各主體：

• 對於兩個 Try again shortly. 主體，請以指數退避重試，且不要推進您的 page 游標，因為失敗的請求未回傳任何資料。
• 如果 Captured content 主體在使用客戶管理金鑰之組織的 messages 端點上持續重複出現，請將其視為持續性的：停止走訪該組織的逐字稿，並在您的金鑰管理服務中檢查金鑰狀態。其他已連結組織中的逐字稿，以及所有地方的工作階段中繼資料，皆不受影響。如果您在之後的執行中重試，請在不帶 page 的情況下重新開始每個工作階段的走訪，因為 messages 頁面游標會在走訪第一頁後 24 小時過期。
• 對於 Try again later. 主體，不要讓走訪保持開啟以等待它清除。在列表端點上，您可以稍後透過不帶 page 參數重新開始來重試（超過 24 小時的列表頁面權杖仍會被接受，但會依目前的保留界限重新評估，因此擱置的走訪可能會跳過工作階段），或縮小 created_at 視窗直到請求成功，並在之後的執行中另行匯出被跳過的範圍。在擷取與 messages 端點上，請跳過該工作階段 ID，繼續進行其餘的匯出，並在之後的執行中重試該工作階段。messages 頁面游標會在走訪第一頁後 24 小時過期，因此當您回到該工作階段時，請在不帶 page 的情況下重新開始其走訪。

如果上述任何狀況在多次執行中重複發生，請聯繫您的 Anthropic 代表，並附上 request-id 回應標頭。對於客戶管理金鑰的情況，請僅在該金鑰可用但錯誤仍持續時才這麼做。

如遇全服務範圍的事件，請查看 status.anthropic.com。

後續步驟