--- title: 處理 Compliance API 錯誤 url: https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors description: 依 HTTP 狀態碼分類的 Compliance API 錯誤回應，以及各錯誤的原因與修正方式。 --- 若要啟用 Compliance API，請參閱[設定 Compliance API](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access)。 本頁依 HTTP 狀態碼列出常見的 Compliance API 錯誤回應，並說明每個錯誤的原因與修正方式。 Compliance API 以標準的 [Anthropic 錯誤格式](https://platform.claude.com/docs/zh-TW/api/errors)回傳錯誤：一個非 2xx 的狀態碼、一個 `request-id` 回應標頭，以及一個 JSON 主體，其中的 `error` 物件包含 `type` 與 `message`。當您向支援團隊提報問題時，請附上 `request-id` 標頭的值。 ```json { "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）則在雲端執行；請參閱[擷取工作階段逐字稿](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-sessions)。 請依據 HTTP 狀態碼與 `error.type` 進行比對，而非訊息字串。訊息足夠穩定，可以複製到操作手冊中，但可能會隨時間改寫；狀態碼與 type 值則屬於 API 合約的一部分。少數共用相同狀態碼與 type 的回應，若回應中帶有 `error.details.error_code` 錯誤代碼，則以該代碼區分，否則以其訊息區分；每種情況都會在適用之處特別說明。 下表讓您一眼就能判斷是否應重試。後續各節會顯示逐字的錯誤主體與修正方式。 | 狀態 | 是否重試？ | 情況 | | ----------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [400 Bad Request](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#400-bad-request) | 否 | 修正請求，或在訊息表示 Compliance API 未啟用時啟用它，然後重新傳送。如果 `error.details.error_code` 為 `transcript_page_read_limit_exceeded`（訊息表示工作階段記錄的某一頁過大而無法讀取），請勿重新傳送相同的請求；[記錄頁面過大](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#transcript-page-too-large)說明了應改採的做法。 | | [401 Unauthorized](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#401-unauthorized) | 否 | 金鑰無法辨識、已停用或已過期；請重新啟用或更換金鑰，然後重新傳送。 | | [403 Forbidden](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#403-forbidden) | 否 | 新增缺少的範圍（scope）或使用正確的金鑰類型，然後重新傳送。 | | [404 Not Found](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#404-not-found) | 通常否 | 若訊息指名某個資源，表示該資源已被刪除或從未存在；請將其從您的佇列中移除。單純的 `Not found` 訊息表示請求未通過驗證（或路徑不存在），而非資源已消失；請參閱[請求未通過驗證](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#request-not-authenticated)。工作階段端點另有兩種情況：在本機工作階段端點上，訊息 `Local sessions are not available.`（每次呼叫都會傳回，包括列表）表示這些端點目前無法供您的上層組織使用，而非工作階段已消失；請保留您佇列中的 ID，並參閱[找不到本機工作階段](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#local-session-not-found)。仍處於 `pending` 狀態的遠端工作階段，在啟動之前其訊息端點會傳回 404；請參閱[找不到遠端工作階段](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#remote-session-not-found)。 | | [409 Conflict](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#409-conflict) | 否 | 請求與資源的目前狀態衝突；請解決衝突（例如卸離子資源），然後重試。 | | [429 Too Many Requests](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#429-too-many-requests) | 是，在 `retry-after` 之後 | 等待 `retry-after` 中的秒數後再重試；請勿推進您的游標。 | | [500 Internal Server Error](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#500-internal-server-error) | 取決於 `x-should-retry` | 重試前請檢查 `x-should-retry` 回應標頭。 | | [502, 503, 504, 529](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#500-internal-server-error) | 是，搭配退避 | 暫時性錯誤；請以指數退避（exponential backoff）重試。例外：部分本機工作階段的 503 並非暫時性錯誤。請參閱[本機工作階段暫時無法使用](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#local-sessions-temporarily-unavailable)。 | ## 400 Bad Request 請求在語法上有效，但伺服器拒絕了某個參數，或該組織未啟用 Compliance API。請修正訊息中指出的原因並重新傳送。有一種 400 不同：[記錄頁面過大](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#transcript-page-too-large)，即使每個參數都有效，本機工作階段訊息端點仍可能針對非常大的工作階段的某一頁傳回此錯誤；該項目說明了應改採的做法，而非重新傳送。 ### 未啟用 Compliance API **Type：** `invalid_request_error` ```text wrap Compliance API is not enabled for this organization ``` **原因：** 金鑰有效，但該金鑰所屬的組織或上層組織未啟用 Compliance API。在 API 啟用之前，每個端點都會傳回此回應；若管理員關閉 API，也會再次傳回此回應。 **修正方式：** 依照[設定 Compliance API](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#set-up-the-compliance-api) 啟用 Compliance API，然後重新傳送請求。 ### 未知的查詢參數 **類型：** `invalid_request_error` ```text wrap Unknown query parameter: 'created_at[gte]'. Did you mean 'created_at.gte'? ``` **原因：** 請求包含端點未定義的查詢參數；Compliance API 會拒絕無法辨識的參數，而非忽略它們。訊息會指出該參數名稱，並且對於相近的錯誤（例如以方括號表示法取代點號，或缺少 `[]` 後綴），會建議已定義的名稱。 **修正方式：** 使用端點的 [Compliance API 參考](https://platform.claude.com/docs/zh-TW/api/compliance)頁面上所列的參數名稱。範圍篩選器使用點號表示法（例如 `created_at.gte`），陣列篩選器需加上 `[]` 後綴（例如 `activity_types[]`），而分頁參數則依端點而定，為 `after_id`、`before_id` 或 `page`。 ### 無效的參數值 **類型：** `invalid_request_error` ```text wrap limit: Input should be less than or equal to 1000 ``` ```text wrap created_at.gte: Input should be a valid datetime or date, invalid character in year ``` ```text wrap activity_types[].0: Input is not one of the permitted values. ``` **原因：** 某個查詢參數的值未通過驗證。訊息以參數名稱開頭（若為陣列參數，後面會接著元素的位置），接著說明未通過的限制條件。此處列出三種常見情況：`limit` 超過端點的上限（訊息中的數字即為該端點的上限）、`created_at.*` 或 `updated_at.*` 的值無法解析為日期或時間戳記，以及 `activity_types[]` 的值不是受支援的活動類型。 **修正方式：** 修正訊息中指出的參數。每個列表端點都有各自的 `limit` 範圍；請參閱對應的 [Compliance API 參考](https://platform.claude.com/docs/zh-TW/api/compliance)頁面上的參數限制。請以 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[]` 值，請參閱[查詢合規活動](https://platform.claude.com/docs/zh-TW/api/compliance/activities/list)。 本機工作階段列表（`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` 時才允許上下限相等。訊息會指出這兩個參數，例如： ```text wrap created_at.lt must be strictly after created_at.gte. ``` ```text wrap 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` ```text wrap Invalid activity_id format: 'activity_invalid123' ``` ```text wrap 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`，因此為不同工作階段或排序順序核發的游標會回傳相同的主體： ```text wrap The page parameter is not a valid cursor for this request. ``` messages 端點上的游標也會在走訪（walk，即完整翻過所有頁面一次）開始後 24 小時過期。過期的游標會回傳： ```text wrap The page cursor has expired. Restart the walk without a page parameter; results will reflect the current retention boundary. ``` 對於第一個主體，請將上一個回應中未經修改的 `next_page` 值重新送至核發它的端點與工作階段。對於過期的游標，請在不帶 `page` 參數的情況下重新開始；新的走訪會反映其開始時生效的保留界限，因此在此期間已超出保留期限的訊息將不再回傳（請參閱[擷取本機工作階段逐字稿](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-sessions#retrieve-a-local-session-transcript)）。 ### 記錄頁面過大 **Type：** `invalid_request_error` **錯誤代碼：** `transcript_page_read_limit_exceeded`，於 `error.details.error_code` 中傳回 ```text wrap 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` 的情況下，重新開始該工作階段的走訪（對其各頁面的一次完整瀏覽；請參閱[擷取本機工作階段對話記錄](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-sessions#retrieve-a-local-session-transcript)），並持續追蹤 `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](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#request-not-authenticated)；而範圍錯誤的有效金鑰則會傳回 [403 Forbidden](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#403-forbidden)。 ### 無效、已停用或已過期的 API 金鑰 **Type：** `authentication_error` ```text wrap API key is invalid. ``` ```text wrap API key has been deactivated. ``` ```text wrap 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](https://claude.ai/admin-settings/api-access)，Admin API 金鑰則請至 Claude Console 中的 [Admin keys](https://platform.claude.com/settings/admin-keys) 頁面（`platform.claude.com/settings/admin-keys`）；已刪除的金鑰無法復原。對於已刪除或已過期的金鑰，請建立新的金鑰並更新您的整合以使用它，如[管理與輪替金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#manage-and-rotate-keys)所述。 ## 403 Forbidden `x-api-key` 中的金鑰有效，但未攜帶端點所接受的範圍。逐字訊息會列出金鑰所攜帶的範圍（`Got:`）以及端點所接受的範圍（讀取端點上為 `Needed one of:`，列出的任一範圍即已足夠；刪除端點上則為 `Needed:`），因此您無需重新檢查 Claude Console 或 claude.ai，即可確認金鑰攜帶了哪些範圍。在讀取端點上，接受的清單還包括 `read:org_audit`，這是一個涵蓋所有 Compliance API 讀取端點的唯讀稽核範圍；請參閱[為 Claude Enterprise 金鑰選擇範圍](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api-keys#choose-scopes-for-a-claude-enterprise-key)。Compliance Access Key 的範圍在建立後即無法變更，因此每個範圍不足的修正方式都會引導您建立新的金鑰，而非編輯現有金鑰。獨立的 Claude Console 組織（沒有上層組織的組織）無法建立 Compliance Access Key，因此需要此類金鑰的修正方式不適用於它；它只能查詢 Activity Feed。 ### Scope 不足：Activity Feed **Type：** `permission_error` ```text wrap 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](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#set-up-the-compliance-api)。 **修正：** Compliance Access Key 的 scope 在建立後不可變更。請建立包含 `read:compliance_activities` 的新金鑰，或使用 Claude Console Admin API 金鑰。請參閱[您需要哪種金鑰？](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#which-key-do-you-need)以了解 Admin API 金鑰在何種條件下具備此 scope。 ### Scope 不足：組織資料 **Type：** `permission_error` ```text wrap 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](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#set-up-the-compliance-api)，並勾選 `read:compliance_org_data`。Admin API 金鑰無法讀取組織中繼資料；必須使用 Compliance Access Key。 ### 已淘汰的 scope：組織設定 **Type：** `permission_error` ```text wrap 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](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#set-up-the-compliance-api) 並勾選 `read:compliance_org_data`，更新您的整合以使用它，然後刪除舊金鑰。已具備 `read:compliance_org_data` 的金鑰不受此淘汰影響。 ### Scope 不足：使用者資料 **Type：** `permission_error` ```text wrap 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](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#set-up-the-compliance-api)。如果該請求確實應僅限於 Activity Feed，請改將 Admin API 金鑰指向 `GET /v1/compliance/activities`。 ### Scope 不足：刪除 **Type：** `permission_error` ```text wrap Missing required scopes. Got: ['read:compliance_user_data'] Needed: ['delete:compliance_user_data'] ``` **原因：** 使用了不具 `delete:compliance_user_data` 的 Compliance Access Key 呼叫聊天、檔案或專案的 `DELETE` 端點。 **修正：** [建立新的 Compliance Access Key](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#set-up-the-compliance-api) 並勾選 `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 則不同：請求未通過驗證（或路徑不存在），任何端點都可能傳回此錯誤，包括列表端點；請參閱[請求未通過驗證](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#request-not-authenticated)。工作階段端點另有兩種情況。在本機工作階段端點上，當這些端點無法供您的上層組織使用時，每次呼叫（包括列表）都會傳回另一個 404 訊息 `Local sessions are not available.`；此訊息與工作階段 ID 無關，且可能是暫時性的。請參閱[找不到本機工作階段](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#local-session-not-found)。在遠端工作階段端點上，仍在佈建中的工作階段（`status` 為 `pending`）尚無記錄，因此其訊息端點在工作階段啟動前會傳回 404。請參閱[找不到遠端工作階段](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#remote-session-not-found)。各修正方式中引用的活動類型字串（例如 `claude_chat_created`）是您可以傳遞給 Activity Feed `activity_types[]` 篩選器的值；所有受支援的值請參閱[查詢合規活動](https://platform.claude.com/docs/zh-TW/api/compliance/activities/list)。 ### 請求未通過驗證 **類型：** `not_found_error` ```text wrap 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](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#401-unauthorized)。 **修正方式：** 在 `x-api-key` 標頭中傳送金鑰並檢查其前綴：Compliance API 只接受 `sk-ant-api01-...` 與 `sk-ant-admin01-...` 金鑰；請參閱[您需要哪種金鑰？](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#which-key-do-you-need)。如果標頭與金鑰都正確，但某個路徑仍傳回 `Not found` 而其他路徑成功，請對照 [Compliance API 參考](https://platform.claude.com/docs/zh-TW/api/compliance)檢查該路徑。 ### 找不到聊天 **Type：** `not_found_error` ```text wrap 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` ```text wrap 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` ```text wrap Generated file not found: 'claude_gen_file_01TbR8wAcCeFhJkLnPqStUvX' ``` ```text wrap Generated file content not found: 'claude_gen_file_01TbR8wAcCeFhJkLnPqStUvX' ``` ```text wrap Artifact version not found: 'claude_artifact_version_01KmNpQrSt3UvWxYz5AbCdEfG' ``` **原因：** 路徑中的 ID 與任何可透過 Compliance API 讀取的工具產生檔案或成品版本都不相符。產生檔案的中繼資料端點會傳回第一個主體，內容端點會傳回第二個主體，而兩個成品端點都會傳回第三個主體。產生的檔案與成品會隨著建立它們的聊天一併刪除，包括使用者在 claude.ai 中刪除該聊天的情況。 **修正方式：** 使用[取得聊天訊息](https://platform.claude.com/docs/zh-TW/api/compliance/apps/chats/messages/list)查詢該 ID 所屬的聊天。如果該聊天的 `deleted_at` 有值，或有 `claude_chat_deleted` 活動指名該聊天，表示內容已消失；請將該 ID 從您的佇列中移除。否則，請對照該聊天訊息上的 `generated_files` 與 `artifacts` 陣列確認 ID。 ### 找不到專案 **Type：** `not_found_error` ```text wrap No project is found with the provided id. ``` ```text wrap 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` ```text wrap No project document found with the provided id. ``` ```text wrap 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` ```text wrap 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）、該工作階段從未存在、該工作階段適用[零資料保留](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention#zero-data-retention-zdr-scope)，或該工作階段的所有活動皆已超過適用於執行它之組織的保留期限。`Local session not found.` 回應沒有暫時性形式，因為本機工作階段沒有佈建（`pending`）狀態；請對照[找不到遠端工作階段](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#remote-session-not-found)，其中 `pending` 工作階段在啟動前會回傳 404。格式不正確的 `clls_` 識別碼工作階段 ID 則會回傳 [400 Bad Request](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#400-bad-request)。 當本機工作階段端點本身對您的上層組織不可用時，這些端點（包括列表端點）會回傳另一則 404 訊息 `Local sessions are not available.`。該回應與工作階段 ID 無關；客戶端的任何金鑰、scope 或設定都無法改變它，且它可能是暫時性的。兩種回應都帶有 `not_found_error` type；區分它們的是訊息文字。 **修正：** 對照 `GET /v1/compliance/apps/sessions/local` 確認工作階段 ID；請參閱[使用者機器上的工作階段](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-sessions#retrieve-local-sessions)。如果該工作階段不再出現在列表中，表示其內容已超過保留期限（或該工作階段因其他原因不再位於您金鑰可讀取的組織中），其逐字稿無法擷取；請將該 ID 從您的佇列中移除。如果每次呼叫（包括列表）都回傳 `Local sessions are not available.`，請保留您佇列中的工作階段 ID，並在下一次排程執行時重試；如果該回應持續出現，請聯絡您的 Anthropic 代表並附上 `request-id` 回應標頭。 ### 找不到遠端工作階段 **Type：** `not_found_error` ```text wrap 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](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#400-bad-request)。 **修正：** 對照 `GET /v1/compliance/apps/sessions/remote` 確認工作階段 ID 及其 `status`；請參閱[雲端中的工作階段](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-sessions#retrieve-remote-sessions)。如果工作階段為 `pending`，請在它離開該狀態後重試。如果該工作階段不再出現在列表中，表示它已被刪除，其逐字稿無法擷取。 ### 找不到組織、角色或群組 **Type：** `not_found_error` ```text wrap 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](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-activity-feed) 中最近的組織、角色或群組活動進行核對。 ### 組織設定不可用 **Type：** `not_found_error` ```text wrap organization `91012d09-e48b-438e-a489-1bebfd8fa6f9` not found in this organization's hierarchy ``` **原因：** `GET /v1/compliance/organizations/{organization_id}/settings` 在三種情況下回傳此 404，這三種情況刻意共用相同的主體，使回應不會揭露組織是否存在：`organization_id` 不是您上層組織的已連結組織之一、該值不是有效的 UUID，或設定端點尚未為您的上層組織啟用。 **修正：** 對照[列出組織](https://platform.claude.com/docs/zh-TW/api/compliance/organizations/list)驗證 ID。如果已知正確的組織 ID 仍回傳 404，表示設定端點尚未為您的上層組織啟用；請聯絡您的 Anthropic 代表。 ## 409 Conflict 請求格式正確且已獲授權，但與資源的目前狀態衝突。主體帶有 `invalid_request_error` 類型，400 回應也使用此類型，因此請透過 409 狀態碼而非 `error.type` 來辨別衝突。 ### 專案有附加的聊天 **類型：** `invalid_request_error` ```text wrap 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[]` 值；請透過[列出組織使用者](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-org-data#list-organization-users)列舉 ID），使用 `DELETE /v1/compliance/apps/chats/{claude_chat_id}` 逐一刪除，然後重試專案刪除。 ## 429 Too Many Requests 對 Compliance API 的請求限制為**每個[上層組織](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api#how-the-compliance-api-works)每分鐘 600 個請求**。此限制是上層組織下所有金鑰（Compliance Access Keys 以及所有已連結組織的 Admin API 金鑰）與所有 `/v1/compliance/*` 端點共用的單一額度；遠端工作階段端點在此之上另有第二個請求額度。對於沒有上層組織的獨立 Claude Console 組織，相同的額度適用於該組織本身，並由其 Admin API 金鑰共用。如果您的整合需要更高的限制，請聯絡您的 Anthropic 代表。 有一種 429 不同：在非常大的工作階段上，本機工作階段訊息端點可能會傳回[伺服器忙於讀取大型對話記錄](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#server-busy-reading-large-transcripts)，這既不是速率限制，也不是對您組織的限制。本節末尾的相關條目說明了如何識別它以及該如何處理。 一旦您的 API 金鑰通過驗證，Compliance API 回應會透過標準的[速率限制回應標頭](https://platform.claude.com/docs/zh-TW/api/rate-limits#response-headers)回報共用額度，讓您的用戶端可以主動節流，而非等待 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 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 ``` ```json { "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 之前消耗一個配額單位。 [本機工作階段端點](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-sessions#retrieve-local-sessions)僅計入共用限制。[遠端工作階段端點](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-sessions#retrieve-remote-sessions)則在共用限制之上另有第二個請求額度，與共用限制一樣以您的上層組織為單位。來自該額度的 429 所帶的 `retry-after` 標頭一律為 `1`（最短等待時間，而非實際重設時間）；該回應上的任何 `anthropic-ratelimit-*` 標頭描述的是共用限制而非此額度，因此如果 429 重複出現，請使用指數退避。有一種 429 並非來自任何請求額度：[伺服器忙於讀取大型對話記錄](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#server-busy-reading-large-transcripts)，僅由本機工作階段訊息端點傳回。 如果您依排程輪詢 [Activity Feed](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-activity-feed)，請將您的總請求速率（跨所有金鑰、已連結組織與並行工作者）控制在共用限制以下。請觀察 `anthropic-ratelimit-requests-remaining`，在達到限制前放慢速度。請參閱[設計您的合規整合](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-integration-patterns#choose-a-feed-consumption-pattern)，以了解如何在視窗輪詢與游標驅動擷取之間做選擇。 ### 伺服器忙於讀取大型對話記錄 **類型：** `rate_limit_error` **錯誤代碼：** `transcript_read_server_busy`，於 `error.details.error_code` 中傳回 ```text wrap 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，它們取決於組織的設定或加密金鑰，而非負載。請參閱[錯誤](https://platform.claude.com/docs/zh-TW/api/errors)以了解全平台的重試語意。 ### 本機工作階段暫時不可用 **Type：** `overloaded_error` ```text wrap The local-sessions index is temporarily unavailable. Try again shortly. ``` ```text wrap Captured content is temporarily unavailable. Try again shortly. ``` ```text wrap The local-sessions index cannot currently evaluate retention overrides for this page. Try again later. ``` **原因：** [本機工作階段端點](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-sessions#retrieve-local-sessions)會以這些主體之一回傳 503。三者共用 `overloaded_error` type，因此這是本頁少數需要依訊息文字而非 `error.type` 來區分情況的錯誤之一： * `index is temporarily unavailable` 回應主體表示工作階段清單因負載或後端狀況而暫時無法使用。這是暫時性的。 * `Captured content` 回應主體表示目前無法傳回某個工作階段的對話記錄內容。這通常也是暫時性的。在使用[客戶管理的加密金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/cmek)的組織中，對於任何包含您的客戶管理金鑰無法解密之內容的頁面，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](https://status.anthropic.com)。 ## 後續步驟 關於存取、scope、保留與整合的常見問題。 全平台的錯誤目錄與重試語意。