Обработка ошибок Compliance API

На этой странице перечислены сообщения ответов, которые возвращает каждая задокументированная конечная точка Compliance API, их причины и способы исправления.

Compliance API возвращает ошибки в формате, согласованном с остальным форматом ошибок Anthropic: код состояния, отличный от 2xx, заголовок ответа request-id и тело JSON с объектом error, содержащим поля type и message. Указывайте значение заголовка request-id при обращении в службу поддержки.

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

Сопоставляйте по error.type, а не по строке сообщения. Сообщения достаточно стабильны, чтобы копировать их в «runbooks» (операционные инструкции), но со временем могут быть переформулированы; значения типов являются частью контракта 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.

Неверный лимит

Тип: invalid_request_error

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

Причина: Параметр запроса limit находился вне допустимого диапазона. Граница, указанная в сообщении, отражает максимум для конкретной вызванной конечной точки.

Исправление: Отправьте limit в пределах диапазона, который принимает конечная точка. У каждой конечной точки списка свой диапазон limit; см. ограничения параметров на соответствующей странице справочника Compliance API.

Неверный идентификатор пагинации

Тип: invalid_request_error

Invalid `after_id`. No activity found for `after_id` "activity_invalid123"

Причина: Курсор after_id или before_id не удалось декодировать как непрозрачный курсор или разобрать как идентификатор активности.

Исправление: Рассматривайте курсоры пагинации как непрозрачные строки. Всегда копируйте значение first_id или last_id, возвращённое предыдущей страницей; останавливайтесь, когда has_more равно false. Не конструируйте курсоры из идентификаторов объектов.

Конечные точки каталога и проектов (пользователи, роли, разрешения ролей, группы, участники групп, проекты и вложения проектов) используют для пагинации непрозрачный токен page вместо after_id и before_id. Рекомендация та же: передавайте значение next_page из предыдущего ответа без изменений и останавливайтесь, когда has_more равно false. Некорректный токен page возвращает ту же ошибку 400 invalid_request_error, что и некорректный after_id или before_id.

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 действителен, но не имеет области доступа («scope»), которую требует конечная точка. В дословном сообщении перечислены области доступа, которые имеет ключ (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.
• Ключ Admin API Claude Console (sk-ant-admin01-...) был создан до того, как Compliance API был включён для организации. Ключи, созданные до включения, не имеют этой области доступа; см. После включения: организации Claude Console.

Исправление: Области доступа Compliance Access Key неизменяемы после создания. Создайте новый ключ, включающий read:compliance_activities, или используйте ключ Admin API Claude Console. См. Какой ключ вам нужен? для условий, при которых ключ 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.
• Был использован ключ Admin API Claude Console (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.
• Был использован ключ Admin API Claude Console (sk-ant-admin01-...). Ключи Admin API имеют только read:compliance_activities и не могут получить read:compliance_user_data, поэтому они не могут вызывать конечные точки чатов, файлов, проектов, вложений проектов, пользователей или участников групп.

Исправление: Используйте Compliance Access Key, созданный в claude.ai с выбранной областью read:compliance_user_data. Если запрос действительно должен быть только для Activity Feed, направьте ключ Admin API на GET /v1/compliance/activities.

Недостаточная область доступа: удаление

Тип: permission_error

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

Причина: Compliance Access Key без delete:compliance_user_data был использован для вызова конечной точки DELETE для чатов, файлов или проектов.

Исправление: Создайте новый Compliance Access Key с выбранной областью delete:compliance_user_data. Область доступа на удаление отделена от read:compliance_user_data, чтобы ключи аудита только для чтения не могли удалять контент.

404 Not Found

Конечная точка разрешилась, но идентификатор ресурса не существует или уже был удалён. Удаления через Compliance API выполняются немедленно и безвозвратно, поэтому 404 для ранее известного идентификатора обычно означает, что контент был окончательно удалён через вызов удаления Compliance API или удалён политикой хранения. Строки типов активности, приведённые в каждом разделе «Исправление» (например, claude_chat_created), — это значения, которые вы можете передать в фильтр activity_types[] Activity Feed; см. Запрос активностей соответствия для всех поддерживаемых значений.

Чат не найден

Тип: not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

Причина: Идентификатор чата в пути не соответствует чату, доступному для чтения через Compliance API. Чат мог быть окончательно удалён через предыдущий вызов Compliance API или удалён политикой хранения вашей организации, либо он может принадлежать организации, которую вызывающий ключ не может читать. Чаты, которые пользователь мягко удалил в claude.ai, не возвращают 404; они остаются доступными для чтения с заполненным полем deleted_at.

Исправление: Сверьте идентификатор чата с недавней активностью claude_chat_created или claude_chat_viewed. Если активность недавняя, а чтение всё равно не удаётся, чат был окончательно удалён (через этот API или по истечении срока политики хранения) или принадлежит организации вне области доступа вашего ключа.

Файл не найден

Тип: not_found_error

No file found with provided id, or it has already been deleted.

Причина: Идентификатор файла не существует или был удалён. Эта ошибка применяется как к файлам, прикреплённым к чату (claude_file_...), так и к файлам проектов.

Исправление: Сверьте с недавними активностями claude_file_uploaded или claude_file_deleted. Если файл был удалён, двоичные данные утрачены; запись активности остаётся в ленте в течение 6-летнего окна хранения.

Проект не найден

Тип: not_found_error

No project is found with the provided 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.

Причина: Идентификатор документа проекта не существует или был удалён. Эта ошибка применяется к текстовым документам проекта (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.). Это происходит, когда идентификатор в пути (org_uuid, role_id или group_id) не существует или больше не принадлежит дереву, которое может читать вызывающий ключ.

Причина: Идентификатор в пути не соответствует записи, доступной для чтения через Compliance API. Роли и группы могут быть удалены, а организации могут быть отсоединены от родительского дерева.

Исправление: Проверьте идентификатор по соответствующей конечной точке списка и сверьте с недавними активностями организаций, ролей или групп в 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[]; перечислите идентификаторы через Список пользователей организации), удалите каждый из них с помощью DELETE /v1/compliance/apps/chats/{claude_chat_id}, а затем повторите удаление проекта.

429 Too Many Requests

Запросы к Compliance API ограничены 600 запросами в минуту на родительскую организацию. Лимит — это единый бюджет, общий для всех ключей под родительской организацией (Compliance Access Keys и ключи 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."
  }
}

Причина: Ваша родительская организация отправила более 600 запросов к /v1/compliance/* в течение 1-минутного окна по всем своим ключам и связанным организациям.

Исправление: Подождите количество секунд, указанное в заголовке retry-after, затем повторите попытку. Если заголовок отсутствует (например, удалён промежуточным узлом), используйте экспоненциальную задержку (начните с 1 секунды, удваивайте до 60 секунд). Не продвигайте курсор пагинации при 429: неудавшийся запрос не вернул данных, поэтому курсор с последней успешной страницы всё ещё корректен.

Запросы, не прошедшие аутентификацию (отсутствующий или нераспознанный ключ, либо ключ Claude API вместо Compliance Access Key или ключа Admin API), отклоняются до ограничителя скорости и не расходуют квоту. Действительный ключ, у которого отсутствует требуемая область доступа конечной точки, расходует одну единицу квоты до возврата 403.

Если вы опрашиваете Activity Feed по расписанию, планируйте совокупную частоту запросов (по всем ключам, связанным организациям и параллельным рабочим процессам) ниже лимита родительской организации. Следите за anthropic-ratelimit-requests-remaining, чтобы замедлиться до достижения лимита. См. Проектирование интеграции соответствия для выбора между опросом по окнам и загрузкой на основе курсора.

500 Internal Server Error

Ответ 500 от Compliance API содержит заголовок ответа x-should-retry: false, когда сбой детерминирован. SDK Anthropic автоматически учитывают этот заголовок. Если вы используете универсальную библиотеку повторных попыток HTTP, которая повторяет запрос при каждом 5xx, подавляйте повторные попытки, когда x-should-retry равен false; повторение этой ошибки завершается идентичным сбоем при каждой попытке.

Ответ 500 без заголовка x-should-retry: false является временным: повторите попытку с экспоненциальной задержкой (начните с 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, которые вы можете использовать для запуска немедленного повторного запроса списка вместо ожидания следующего интервала опроса.

Дальнейшие шаги