處理 Compliance API 錯誤

本頁列出每個已記錄的 Compliance API 端點所回傳的回應訊息、原因及修正方式。

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

{
  "error": {
    "type": "authentication_error",
    "message": "The API key provided is invalid or has been revoked."
  }
}

請依據 error.type 進行比對，而非訊息字串。訊息內容足夠穩定，可複製到執行手冊中，但可能會隨時間重新措辭；type 值則是 API 合約的一部分。本機工作階段端點有少數已記錄的例外情況，其中共用同一 type 的回應需透過訊息內容來區分；每個例外都會在適用之處特別說明。

下表讓您一目了然地判斷是否應重試。後續各節會顯示逐字的錯誤主體及修正方式。



400 Bad Request

請求在語法上有效，但包含伺服器拒絕的參數。請修正參數後重試。



無效的時間戳記格式

類型： invalid_request_error

The `created_at.gte` parameter contains an invalid timestamp format. Timestamps must be provided in RFC 3339 format e.g., "2024-03-01T00:00:00Z". Got "2024-01-01".

原因： created_at.* 或 updated_at.* 的值（.gte、.gt、.lte、.lt）無法解析為日期時間。訊息會指出失敗的參數名稱，並回顯所傳送的值。

修正方式： 傳送包含時間和時區的完整 RFC 3339 時間戳記，例如 2024-03-01T00:00:00Z 或 2024-03-01T00:00:00+00:00。

當同時提供兩個時間界限且 created_at.lt 並非嚴格晚於 created_at.gte 時，本機工作階段列表（GET /v1/compliance/apps/sessions/local）也會回傳 400 invalid_request_error。主體內容如下：

created_at.lt must be strictly after created_at.gte.

請傳送晚於 created_at.gte 的 created_at.lt，或省略其中一個界限。



無效的 limit

類型： invalid_request_error

The limit parameter must be between 1 and 1000, inclusive. Got 1500.

原因： limit 查詢參數超出可接受的範圍。訊息中指出的界限反映的是所呼叫之特定端點的最大值。

修正方式： 傳送在端點可接受範圍內的 limit。每個列表端點都有自己的 limit 範圍；請參閱對應的 Compliance API 參考頁面上的參數限制。

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



無效的分頁 ID

類型： invalid_request_error

Invalid `after_id`. No activity found for `after_id` "activity_invalid123"

原因： after_id 或 before_id 游標無法解碼為不透明游標，或無法解析為活動 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。

兩個本機工作階段端點（列表端點和訊息端點）對於任何無法解碼的 page 值都會回傳以下 400 invalid_request_error，例如在您儲存後被截斷或修改的權杖，或由不同端點或不同上層組織下發出的權杖。在本機工作階段訊息端點（GET /v1/compliance/apps/sessions/local/{session_id}/messages）上，每個 page 游標也會繫結至發出它的工作階段和 order，因此為不同工作階段或排序順序發出的游標會回傳相同的主體：

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

訊息端點上的游標也會在遍歷（一次完整翻閱所有頁面）開始後 24 小時過期。過期的游標會回傳：

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

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



401 Unauthorized

x-api-key 標頭遺失或與已知金鑰不符。具有錯誤範圍的有效金鑰會改為回傳 403 Forbidden。



無效的 API 金鑰

類型： authentication_error

The API key provided is invalid or has been revoked.

原因： x-api-key 中的金鑰不存在、已被刪除或已被停用。遺失或空白的 x-api-key 標頭會回傳相同的主體，因此請同時檢查您的密鑰儲存區和金鑰的撤銷狀態。

修正方式： 確認金鑰值，檢查它是否已在 claude.ai（Compliance Access Keys）或 Claude Console（Admin API keys）中被刪除，並確認它已啟用。請參閱設定 Compliance API。



403 Forbidden

x-api-key 中的金鑰有效，但不具備端點所需的範圍。逐字訊息會列出金鑰所具備的範圍（Got:）和端點所需的範圍（Needed:），因此您無需重新檢查 Claude Console 或 claude.ai 即可確認金鑰所具備的範圍。Compliance Access Key 的範圍在建立後即不可變更，因此每個範圍不足的修正方式都會指示您建立新金鑰，而非編輯現有金鑰。



範圍不足：Activity Feed

類型： permission_error

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

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

• 建立 Compliance Access Key（sk-ant-api01-...）時未選取 read:compliance_activities 範圍。
• 在組織尚未啟用 Compliance API 時建立了 Claude Console Admin API key（sk-ant-admin01-...）。在 Compliance API 未啟用時建立的金鑰不具備此範圍；請參閱設定 Compliance API。

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



範圍不足：組織資料

類型： permission_error

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

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

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

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



已淘汰的範圍：組織設定

類型： permission_error

Missing required scopes. Got: ['read:compliance_org_settings'] Needed: ['read:compliance_org_data']

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

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



範圍不足：使用者資料

類型： permission_error

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

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

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

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



範圍不足：刪除

類型： 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。刪除範圍與 read:compliance_user_data 是分開的，以確保唯讀稽核金鑰無法刪除內容。



404 Not Found

端點已解析，但資源 ID 不存在或已被刪除。Compliance API 的刪除是立即且永久的，因此對先前已知 ID 的 404 通常表示該內容已透過 Compliance API 刪除呼叫被硬刪除，或已被保留政策移除。一個例外是仍處於 pending 狀態的遠端工作階段，其訊息端點會暫時回傳 404，直到工作階段開始為止；請參閱找不到遠端工作階段。每個修正方式中引用的活動類型字串（例如 claude_chat_created）是您可以傳遞給 Activity Feed activity_types[] 篩選器的值；請參閱查詢合規活動以了解所有支援的值。

本機工作階段沒有 pending 狀態，因此 Local session not found. 的 404 絕不會是暫時性的；請參閱找不到本機工作階段以了解其原因，以及另一個 Local sessions are not available. 回應，該回應不依賴於工作階段 ID 且可能是暫時性的。



找不到對話

類型： not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

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

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



找不到檔案

類型： not_found_error

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

原因： 檔案 ID 不存在或已被刪除。此錯誤適用於對話附加檔案（claude_file_...）和專案檔案。

修正方式： 對照最近的 claude_file_uploaded 或 claude_file_deleted 活動進行核對。如果檔案已被刪除，二進位檔案即已消失；活動記錄會在 6 年保留期間內保留於動態中。



找不到專案

類型： not_found_error

No project is found with the provided id.

原因： 專案 ID 不存在或已被刪除。

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



找不到專案文件

類型： not_found_error

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

原因： 專案文件 ID 不存在或已被刪除。此錯誤適用於文字專案文件（claude_proj_doc_...），而非專案檔案。

修正方式： 使用 GET /v1/compliance/apps/projects/{project_id}/attachments 列出目前的附件。如果文件遺失，表示它已被刪除；如果您只需要中繼資料，請透過 claude_project_document_uploaded 活動記錄擷取。



找不到遠端工作階段

類型： not_found_error

Remote session not found.

原因： 傳遞給 GET /v1/compliance/apps/sessions/remote/{session_id}/messages 的工作階段 ID 與可透過 Compliance API 讀取的工作階段逐字稿不符。當工作階段 ID（cse_...）不存在或工作階段已被刪除、工作階段屬於您的金鑰無法讀取的組織，或工作階段的 status 仍為 pending 時，就會發生此情況：待處理的工作階段尚無逐字稿，因此訊息端點會回傳 404，直到工作階段開始為止。格式不正確的 cse_ 識別碼工作階段 ID 會改為回傳 400 Bad Request。

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



找不到本機工作階段

類型： 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）、工作階段從未存在、該工作階段適用零資料保留，或工作階段的所有活動都已超過執行該工作階段之組織所適用的保留期限時，兩個端點都會回傳這一則訊息，且不區分原因。與遠端工作階段不同，本機工作階段沒有 pending 狀態，因此 Local session not found. 回應沒有暫時性的形式。格式不正確的 clls_ 識別碼工作階段 ID 會改為回傳 400 Bad Request。

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

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



找不到組織、角色或群組

類型： 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 中最近的組織、角色或群組活動進行核對。



組織設定無法使用

類型： 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

請求格式正確且已授權，但與資源的目前狀態衝突。



專案有附加的對話

類型： conflict_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 Key 和所有已連結組織的 Admin API key）以及所有 /v1/compliance/* 端點共用；遠端工作階段端點在此之上還有第二個請求預算。對於沒有上層組織的獨立 Claude Console 組織，相同的預算適用於該組織本身，並由其 Admin API key 共用。如果您的整合需要更高的限制，請聯絡您的 Anthropic 代表。

一旦您的 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 key）會在速率限制器之前被拒絕，不會消耗配額。具備有效金鑰但缺少端點所需範圍的請求，會在回傳 403 之前消耗一個配額單位。

遠端工作階段端點在共用限制之上還有第二個請求預算，同樣以您的上層組織為鍵。來自該預算的 429 會帶有始終為 1 的 retry-after 標頭（這是最小等待時間，而非實際重設時間）；該回應上的任何 anthropic-ratelimit-* 標頭描述的是共用限制而非此預算，因此如果 429 重複出現，請以指數方式退避。本機工作階段端點沒有第二個預算，僅計入共用限制。

如果您按排程輪詢 Activity Feed，請將您的總請求速率（跨所有金鑰、已連結組織和並行工作程序）預算控制在共用限制以下。監控 anthropic-ratelimit-requests-remaining 以在達到限制前減速。請參閱設計您的合規整合以在視窗輪詢和游標驅動擷取之間做出選擇。



500 Internal Server Error

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

不帶 x-should-retry: false 標頭的 500 是暫時性的：請以指數退避方式重試（從 1 秒開始，倍增至最多 60 秒）。502、503、504 和 529 回應也適用相同規則。接下來描述的一個本機工作階段 503 與資料相關而非暫時性。請參閱錯誤以了解平台層級的重試語意。



本機工作階段暫時無法使用

類型： 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 並帶有上述其中一個主體。前兩個表示工作階段列表或工作階段的擷取內容暫時無法使用；這是與負載或後端相關的暫時性狀況。第三個主體（在擷取和訊息端點上顯示為 for this session 而非 for this page）表示適用於所請求範圍內一或多個工作階段的保留或資料處理設定尚無法評估。這取決於執行該工作階段之組織的資料和設定，而非負載，且可能持續較長時間。這三個主體都共用 overloaded_error 類型，因此這是本頁少數需要透過訊息文字而非 error.type 來區分需要不同處理方式之狀況的情況之一。

修正方式： 對於兩個 Try again shortly. 主體，請以指數退避方式重試，且不要推進您的 page 游標，因為失敗的請求未回傳任何資料。對於 Try again later. 主體，請勿保持遍歷開啟以等待其清除。在列表端點上，可以稍後在不帶 page 參數的情況下重新開始以重試（超過 24 小時的列表頁面權杖仍會被接受，但會根據目前的保留期限邊界重新評估，因此擱置的遍歷可能會略過工作階段），或縮小 created_at.gte 和 created_at.lt 視窗直到請求成功，並在稍後的執行中單獨匯出略過的範圍。在擷取和訊息端點上，請略過該工作階段 ID，繼續匯出其餘部分，並在稍後的執行中重試該工作階段；訊息頁面游標會在遍歷的第一頁後 24 小時過期，因此當您返回該工作階段時，請在不帶 page 的情況下重新開始該工作階段的遍歷。如果此狀況在多次執行中重複出現，請聯絡您的 Anthropic 代表並附上 request-id 回應標頭。

如需了解服務層級的事件，請查看 status.anthropic.com。



後續步驟