Обработка ошибок 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, а не по строке сообщения. Сообщения достаточно стабильны, чтобы копировать их в runbook-и, но со временем их формулировка может измениться; значения типов являются частью контракта 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 возвращает ту же ошибку 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 действителен, но не несёт область действия, требуемую конечной точкой. Дословное сообщение перечисляет области действия, которые несёт ключ (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 был включён для организации. Ключи, созданные до включения, не несут эту область действия; см. Настройка Compliance API.

Исправление: Области действия 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_org_settings'] Needed: ['read:compliance_org_data']

Причина: Область действия read:compliance_org_settings была выведена из эксплуатации 30 июня 2026 года. GET /v1/compliance/organizations/{organization_id}/settings теперь требует read:compliance_org_data, ту же область действия, что и другие конечные точки организаций, и устаревшая область действия больше ничего не авторизует. Compliance Access Key, который несёт только read:compliance_org_settings, возвращает эту ошибку при каждом вызове конечной точки настроек, даже если ключ работал до вывода из эксплуатации. Устаревшую область действия больше нельзя выбрать или предоставить при создании ключа.

Исправление: Области действия Compliance Access Key неизменяемы после создания. Создайте новый Compliance Access Key с выбранным read:compliance_org_data, обновите вашу интеграцию для его использования, затем удалите старый ключ. Ключ, который уже несёт read:compliance_org_data, не затронут выводом из эксплуатации.



Недостаточная область действия: данные пользователей

Тип: 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

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



Чат не найден

Тип: not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

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

Исправление: Подтвердите ID чата по недавней активности claude_chat_created или claude_chat_viewed. Если активность недавняя, а чтение всё равно не удаётся, чат был окончательно удалён (через этот 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.



Настройки организации недоступны

Тип: not_found_error

organization `91012d09-e48b-438e-a489-1bebfd8fa6f9` not found in this organization's hierarchy

Причина: GET /v1/compliance/organizations/{organization_id}/settings возвращает этот 404 в трёх случаях, которые намеренно используют одно и то же тело, чтобы ответ не раскрывал, существует ли организация: organization_id не является одной из связанных организаций вашей родительской организации, значение не является действительным UUID, или конечная точка настроек ещё не включена для вашей родительской организации.

Исправление: Проверьте ID через Список организаций. Если заведомо корректный ID организации всё равно возвращает 404, конечная точка настроек ещё не включена для вашей родительской организации; свяжитесь с вашим представителем Anthropic.



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} (фильтр project_ids[] требует хотя бы одного значения user_ids[]; перечислите ID через Список пользователей организации), удалите каждый из них с помощью 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.



Следующие шаги