处理 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

请求在语法上有效，但包含服务器拒绝的参数。修正参数后重试。

时间戳格式无效

类型： 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 Keys）或 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 之前创建的。启用之前创建的密钥不具备该作用域；请参阅启用后：Claude Console 组织。

解决方法： 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_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 中最近的组织、角色或群组活动进行核对。

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} 列出项目的聊天（聊天列表端点至少需要一个 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。

超出最大响应大小

类型： 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 活动类型呈现成员资格事件，您可以使用这些事件触发立即重新列出，而不是等待下一个轮询间隔。

后续步骤