# 处理 Compliance API 错误

每条 Compliance API 错误消息的原因和修复方法，按 HTTP 状态码分类。

---

<Note>
  Compliance API 需申请开通。Claude Enterprise 组织可访问完整 API；Claude Console 组织仅可访问[活动动态](/docs/en/manage-claude/compliance-activity-feed)。请参阅[获取 Compliance API 访问权限](/docs/en/manage-claude/compliance-api-access)。
</Note>

本页列出每个已记录的 Compliance API 端点返回的响应消息、原因和修复方法。

Compliance API 返回的错误格式与 [Anthropic 错误格式](/docs/en/api/errors)一致：非 2xx 状态码、`request-id` 响应头以及包含 `error` 对象（含 `type` 和 `message`）的 JSON 正文。向支持团队升级时请包含 `request-id` 头的值。

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

请根据 `error.type` 进行匹配，而非消息字符串。消息足够稳定，可以复制到运维手册中，但可能会随时间调整措辞；type 值是 API 契约的一部分。

下表让您一目了然地判断是否应重试。后续各节显示逐字错误正文和修复方法。

| 状态                                                  | 是否重试？                  | 说明                                                                  |
| ---------------------------------------------------- | --------------------------- | --------------------------------------------------------------------- |
| [400 Bad Request](#400-bad-request)                  | 否                          | 修复请求后重新发送。                                                   |
| [401 Unauthorized](#401-unauthorized)                | 否                          | 修复或轮换密钥后重新发送。                                             |
| [403 Forbidden](#403-forbidden)                      | 否                          | 添加缺失的权限范围或使用正确的密钥类型后重新发送。                      |
| [404 Not Found](#404-not-found)                      | 否                          | 资源已被删除或从未存在；从队列中移除。                                  |
| [409 Conflict](#409-conflict)                        | 否                          | 请求与资源的当前状态冲突；解决冲突（如分离子资源）后重试。              |
| [429 Too Many Requests](#429-too-many-requests)      | 是，在 `retry-after` 之后   | 等待 `retry-after` 中的秒数后重试；不要推进游标。                       |
| [500 Internal Server Error](#500-internal-server-error) | 取决于 `x-should-retry`  | 重试前检查 `x-should-retry` 响应头。                                   |
| [502、503、504、529](#500-internal-server-error)     | 是，使用退避策略            | 瞬时错误；使用指数退避重试。                                           |

## 400 Bad Request

请求语法正确但包含服务器拒绝的参数。修复参数后重试。

### 无效的时间戳格式

**类型：** `invalid_request_error`

```text
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`

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

**原因：** `limit` 查询参数超出了可接受范围。消息中指定的上限反映了所调用特定端点的最大值。

**修复：** 发送端点接受范围内的 `limit`。每个列表端点都有自己的 `limit` 范围；请参阅相应 [Compliance API 参考](/docs/en/api/compliance)页面上的参数约束。

### 无效的分页 ID

**类型：** `invalid_request_error`

```text
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](#403-forbidden)。

### 无效的 API 密钥

**类型：** `authentication_error`

```text
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 key）中被删除，并确认它已启用。请参阅[获取 Compliance API 访问权限](/docs/en/manage-claude/compliance-api-access)。

## 403 Forbidden

`x-api-key` 中的密钥有效但不具有端点所需的权限范围。逐字消息列出了密钥具有的权限范围（`Got:`）和端点所需的权限范围（`Needed:`），因此您可以在不重新检查 Claude Console 或 claude.ai 的情况下确认密钥具有什么权限。Compliance Access Key 的权限范围在创建后不可更改，因此每个权限不足的修复都指引您创建新密钥而非编辑现有密钥。

### 权限范围不足：活动动态

**类型：** `permission_error`

```text
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-...`）。在开通之前创建的密钥不具有此权限范围；请参阅[开通后：Claude Console 组织](/docs/en/manage-claude/compliance-api-access#after-enablement-claude-console-organizations)。

**修复：** Compliance Access Key 的权限范围在创建后不可更改。创建包含 `read:compliance_activities` 的新密钥，或使用 Claude Console Admin API key。请参阅[您需要哪种密钥？](/docs/en/manage-claude/compliance-api-access#which-key-do-you-need)了解 Admin API key 在何种条件下具有此权限范围。

### 权限范围不足：组织数据

**类型：** `permission_error`

```text
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](/docs/en/manage-claude/compliance-api-access#create-a-compliance-access-key) 并选择 `read:compliance_org_data`。Admin API key 无法读取组织元数据；需要使用 Compliance Access Key。

### 权限范围不足：用户数据

**类型：** `permission_error`

```text
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 中创建的 [Compliance Access Key](/docs/en/manage-claude/compliance-api-access#create-a-compliance-access-key) 并选择 `read:compliance_user_data`。如果请求确实仅限于活动动态，请将 Admin API key 指向 `GET /v1/compliance/activities`。

### 权限范围不足：删除

**类型：** `permission_error`

```text
Missing required scopes. Got: ['read:compliance_user_data'] Needed: ['delete:compliance_user_data']
```

**原因：** 使用不具有 `delete:compliance_user_data` 权限的 Compliance Access Key 调用了聊天、文件或项目的 `DELETE` 端点。

**修复：** [创建新的 Compliance Access Key](/docs/en/manage-claude/compliance-api-access#create-a-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_types[]` 筛选参数的值；请参阅[查询合规活动](/docs/en/api/compliance/activities/list)了解所有支持的值。

### 聊天未找到

**类型：** `not_found_error`

```text
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`

```text
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`

```text
No project is found with the provided id.
```

**原因：** 项目 ID 不存在或已被删除。

**修复：** 根据最近的 `claude_project_created` 或 `claude_project_deleted` 活动进行核对。即使项目本身已不存在，活动动态仍会继续暴露项目的生命周期事件。

### 项目文档未找到

**类型：** `not_found_error`

```text
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`

```text
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，并根据[活动动态](/docs/en/manage-claude/compliance-activity-feed)中最近的组织、角色或群组活动进行核对。

## 409 Conflict

请求格式正确且已授权，但与资源的当前状态冲突。

### 项目仍有附加聊天

**类型：** `conflict_error`

```text
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[]` 值；通过[列出组织用户](/docs/en/manage-claude/compliance-org-data#list-organization-users)枚举 ID），使用 `DELETE /v1/compliance/apps/chats/{claude_chat_id}` 删除每个聊天，然后重试项目删除。

## 429 Too Many Requests

Compliance API 的请求限制为**每个[父组织](/docs/en/manage-claude/compliance-api#how-the-compliance-api-works)每分钟 600 次请求**。该限制是父组织下所有密钥（Compliance Access Key 和所有关联组织的 Admin API key）以及所有 `/v1/compliance/*` 端点共享的单一预算。如果您的集成需要更高的限制，请联系您的 Anthropic 代表。

一旦您的 API 密钥通过身份验证，每个 Compliance API 响应都包含标准的[速率限制响应头](/docs/en/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."
  }
}
```

**原因：** 您的父组织在 1 分钟窗口内向 `/v1/compliance/*` 发送了超过 600 次请求（跨所有密钥和关联组织）。

**修复：** 等待 `retry-after` 头中的秒数后重试。如果该头缺失（例如被中间件剥离），请退回到指数退避（从 1 秒开始，翻倍到 60 秒）。在 429 时不要推进分页游标：失败的请求未返回数据，因此上一个成功页面的游标仍然正确。

身份验证失败的请求（缺失或无法识别的密钥，或使用 Claude API 密钥而非 Compliance Access Key 或 Admin API key）会在速率限制器之前被拒绝，不消耗配额。缺少端点所需权限范围的有效密钥会在返回 403 之前消耗一个配额单位。

如果您按计划轮询[活动动态](/docs/en/manage-claude/compliance-activity-feed)，请将聚合请求速率（跨所有密钥、关联组织和并发工作线程）控制在父组织限制以下。观察 `anthropic-ratelimit-requests-remaining` 以在达到限制前减速。请参阅[设计您的合规集成](/docs/en/manage-claude/compliance-integration-patterns#choose-a-feed-consumption-pattern)了解窗口轮询和游标驱动摄取之间的选择。

## 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 响应同理。请参阅[错误](/docs/en/api/errors)了解平台级重试语义。

有关全服务事件，请查看 [status.anthropic.com](https://status.anthropic.com)。

### 超过最大响应大小

**类型：** `api_error`

```text
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 支持以获取更大组织列表的帮助。如果您轮询此端点来跟踪组织成员关系变化，一旦上限问题得到解决，定期重新列出仍是最可靠的方法；它可以捕获添加和移除，无论父子关系的哪一方发起。[活动动态](/docs/en/manage-claude/compliance-activity-feed)也通过 `org_deletion_requested`、`org_deleted_via_bulk`、`org_parent_join_proposal_created` 和 `org_join_proposal_decided` 活动类型呈现成员事件，您可以使用它们触发立即重新列出，而不是等待下一个轮询间隔。

## 后续步骤

<CardGroup cols={2}>
  <Card title="Compliance API 常见问题" href="/docs/en/manage-claude/compliance-faq">
    关于访问、权限范围、保留和集成的常见问题。
  </Card>
  <Card title="错误" href="/docs/en/api/errors">
    平台级错误目录和重试语义。
  </Card>
</CardGroup>