處理 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 合約的一部分。

下表讓您一眼判斷是否應重試。後續各節會顯示完整的錯誤主體及修正方式。

400 Bad Request

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

無效的時間戳記格式

Type： 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

Type： invalid_request_error

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

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

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

無效的分頁 ID

Type： 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 金鑰

Type： 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

Type： 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 key（sk-ant-admin01-...）是在組織啟用 Compliance API 之前建立的。啟用前建立的金鑰不具備此範圍；請參閱啟用後：Claude Console 組織。

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

範圍不足：組織資料

Type： 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。

範圍不足：使用者資料

Type： 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。

範圍不足：刪除

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

404 Not Found

端點已解析，但資源 ID 不存在或已被刪除。Compliance API 的刪除是立即且永久的，因此對先前已知 ID 收到 404 通常表示該內容已透過 Compliance API 刪除呼叫被硬刪除，或已被保留政策移除。每個修正方式中引用的活動類型字串（例如 claude_chat_created）是您可以傳遞給 Activity Feed activity_types[] 篩選器的值；請參閱查詢合規活動以取得所有支援的值。

找不到對話

Type： 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 或因保留政策到期），或屬於您金鑰範圍之外的組織。

找不到檔案

Type： 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 年保留期間內持續保留於動態中。

找不到專案

Type： not_found_error

No project is found with the provided id.

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

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

找不到專案文件

Type： 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 活動記錄擷取。

找不到組織、角色或群組

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

409 Conflict

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

專案仍有附加的對話

Type： 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} 列出專案的對話（對話列表端點需要至少一個 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/* 端點共用。如果您的整合需要更高的限制，請聯絡您的 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 key）會在速率限制器之前被拒絕，不會消耗配額。具備有效金鑰但缺少端點所需範圍的請求，會在回傳 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。

超過最大回應大小

Type： api_error

Response exceeds maximum of 1,000 organizations. Contact support for assistance with larger organization lists.

原因： 不具分頁功能的列表端點（特別是 GET /v1/compliance/organizations）原本會回傳超過其 1,000 筆記錄硬上限的資料。

修正方式： 組織端點會在單次呼叫中回傳完整樹狀結構，最多 1,000 個連結組織。如果您的樹狀結構超過 1,000 個，請聯絡 Anthropic 支援團隊以取得處理較大組織列表的協助。如果您原本是輪詢此端點以追蹤組織成員資格變更，一旦上限問題解決後，定期重新列出仍是最可靠的方法；無論是父子關係的哪一方發起變更，此方法都能捕捉到新增和移除。Activity Feed 也會透過 org_deletion_requested、org_deleted_via_bulk、org_parent_join_proposal_created 和 org_join_proposal_decided 活動類型呈現成員資格事件，您可以利用這些事件觸發立即重新列出，而不必等待下一個輪詢間隔。

後續步驟