處理 Compliance API 錯誤

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

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

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

請比對 error.type，而不是訊息字串。訊息的穩定性足以複製到操作手冊中，但可能會隨時間改寫；type 值才是 API 合約的一部分。

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



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。



無效的 limit

類型： invalid_request_error

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

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

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



無效的分頁 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 時停止。格式錯誤的 page 權杖會回傳與格式錯誤的 after_id 或 before_id 相同的 400 invalid_request_error。



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 Key）或 Claude Console（Admin API 金鑰）中被刪除，並確認它已啟用。請參閱設定 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 範圍。
• Claude Console Admin API 金鑰（sk-ant-admin01-...）是在組織啟用 Compliance API 之前建立的。在啟用之前建立的金鑰不具備此範圍；請參閱設定 Compliance API。

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



範圍不足：組織資料

類型： 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 金鑰（sk-ant-admin01-...）。Admin API 金鑰僅具備 read:compliance_activities，無法讀取組織中繼資料。

修正： 建立新的 Compliance Access Key 並選取 read:compliance_org_data。Admin API 金鑰無法讀取組織中繼資料；必須使用 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 金鑰（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。



範圍不足：刪除

類型： 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 刪除呼叫被硬刪除，或已被保留政策移除。每個修正方式中引用的活動類型字串（例如 claude_chat_created）是您可以傳入 Activity Feed activity_types[] 篩選器的值；請參閱查詢合規活動以了解所有支援的值。



找不到聊天

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

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 金鑰）以及所有 /v1/compliance/* 端點共用的單一預算。如果您的整合需要更高的限制，請聯絡您的 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."
  }
}

原因： 您的父層組織在 1 分鐘的時間窗口內，透過其所有金鑰與已連結組織，向 /v1/compliance/* 傳送了超過 600 個請求。

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

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

如果您按排程輪詢 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 回應也適用相同做法。請參閱錯誤以了解平台層級的重試語意。

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



後續步驟