Compliance API 오류 처리

이 페이지에서는 일반적인 Compliance API 오류 응답을 HTTP 상태 코드별로 정리하고, 각 오류의 원인과 해결 방법을 설명합니다.

Compliance API는 표준 Anthropic 오류 형식으로 오류를 반환합니다. 즉, 2xx가 아닌 상태 코드, request-id 응답 헤더, 그리고 type과 message를 포함하는 error 객체가 담긴 JSON 본문입니다. 지원팀에 문의할 때는 request-id 헤더 값을 포함하세요.

{
  "error": {
    "type": "permission_error",
    "message": "Missing required scopes. Got: ['read:compliance_activities'] Needed one of: ['read:compliance_user_data', 'read:org_audit']"
  }
}

이 페이지에서 로컬 세션은 사용자의 머신에서 실행되고 원격 세션은 클라우드에서 실행됩니다. 세션 트랜스크립트 조회를 참조하세요.

메시지 문자열이 아니라 HTTP 상태 코드와 error.type을 기준으로 오류를 판별하세요. 메시지는 "runbook"(운영 매뉴얼)에 복사해 둘 수 있을 만큼 안정적이지만 시간이 지나면서 문구가 바뀔 수 있습니다. 반면 상태 코드와 type 값은 API 계약의 일부입니다. 상태 코드와 type이 같은 몇몇 응답은, 응답에 오류 코드가 포함된 경우 error.details.error_code의 오류 코드로, 그렇지 않은 경우 메시지로 구분합니다. 해당되는 경우마다 이를 명시합니다.

다음 표는 재시도 여부를 한눈에 알려 줍니다. 이어지는 각 섹션에서는 오류 본문 원문과 해결 방법을 보여 줍니다.

400 Bad Request

요청은 구문상 유효했지만, 서버가 매개변수를 거부했거나 조직에 Compliance API가 활성화되어 있지 않습니다. 메시지에 명시된 원인을 수정하고 다시 보내세요. 한 가지 400은 다릅니다. 트랜스크립트 페이지가 너무 큼은 모든 매개변수가 유효하더라도 매우 큰 세션의 페이지에 대해 로컬 세션 메시지 엔드포인트가 반환할 수 있는 오류이며, 해당 항목에서 다시 보내는 대신 해야 할 일을 설명합니다.

Compliance API가 활성화되지 않음

Type: invalid_request_error

Compliance API is not enabled for this organization

원인: 키는 유효하지만, 키가 속한 조직 또는 상위 조직에 Compliance API가 활성화되어 있지 않습니다. API가 활성화되기 전까지는 모든 엔드포인트가 이 응답을 반환하며, 관리자가 API를 비활성화하면 다시 이 응답을 반환합니다.

해결 방법: Compliance API 설정의 안내에 따라 Compliance API를 활성화한 후 요청을 다시 보내세요.

알 수 없는 쿼리 매개변수

유형: invalid_request_error

Unknown query parameter: 'created_at[gte]'. Did you mean 'created_at.gte'?

원인: 요청에 엔드포인트에서 정의하지 않은 쿼리 매개변수가 포함되어 있습니다. Compliance API는 인식할 수 없는 매개변수를 무시하지 않고 거부합니다. 메시지에는 해당 매개변수의 이름이 표시되며, 점 대신 대괄호 표기법을 사용했거나 [] 접미사를 빠뜨린 경우처럼 정의된 이름과 거의 비슷하면 올바른 이름을 제안합니다.

해결 방법: 엔드포인트의 Compliance API 레퍼런스 페이지에 나와 있는 매개변수 이름을 사용하세요. 범위 필터는 점 표기법을 사용하고(예: created_at.gte), 배열 필터에는 [] 접미사를 붙이며(예: activity_types[]), 페이지네이션 매개변수는 엔드포인트에 따라 after_id, before_id 또는 page입니다.

잘못된 매개변수 값

유형: invalid_request_error

limit: Input should be less than or equal to 1000

created_at.gte: Input should be a valid datetime or date, invalid character in year

activity_types[].0: Input is not one of the permitted values.

원인: 쿼리 매개변수의 값이 유효성 검사를 통과하지 못했습니다. 메시지는 매개변수 이름(배열 매개변수인 경우 그 뒤에 요소의 위치)으로 시작하고, 이어서 충족하지 못한 제약 조건을 설명합니다. 위에는 세 가지 일반적인 경우가 나와 있습니다. 엔드포인트의 최댓값을 초과하는 limit(메시지에 표시된 숫자가 해당 엔드포인트의 최댓값입니다), 날짜나 타임스탬프로 파싱할 수 없는 created_at.* 또는 updated_at.* 값, 그리고 지원되지 않는 활동 유형을 지정한 activity_types[] 값입니다.

해결 방법: 메시지에 명시된 매개변수를 수정하세요. 목록 엔드포인트마다 limit 범위가 다르므로, 해당 Compliance API 레퍼런스 페이지에서 매개변수 제약 조건을 확인하세요. 타임스탬프는 UTC 오프셋을 명시한 RFC 3339 형식으로 보내세요(예: 2024-03-01T00:00:00Z 또는 2024-03-01T00:00:00+00:00). 로컬 세션 목록은 오프셋이 없는 타임스탬프를 거부합니다(created_at.gte: Input should have timezone info). 지원되는 activity_types[] 값은 컴플라이언스 활동 쿼리를 참조하세요.

로컬 세션 목록(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를 함께 사용할 때만 허용됩니다. 메시지에는 두 매개변수의 이름이 표시됩니다. 예:

created_at.lt must be strictly after created_at.gte.

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)도 잘라내기(truncation) 매개변수를 같은 방식으로 검증합니다. tool_use_input_max_bytes와 tool_result_max_bytes는 각각 양의 바이트 수 또는 -1(서버 최댓값)만 허용하므로, 0과 같은 값을 보내면 동일한 400 invalid_request_error가 반환됩니다.

잘못된 페이지네이션 커서

Type: invalid_request_error

Invalid activity_id format: 'activity_invalid123'

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로 커서를 직접 구성하지 마세요.

디렉터리, 프로젝트, 세션 엔드포인트(조직, 사용자, 역할, 역할 권한, 그룹, 그룹 멤버, 프로젝트, 프로젝트 첨부 파일, 로컬 및 원격 세션, 세션 메시지)는 after_id와 before_id 대신 불투명한 page 토큰으로 페이지를 나눕니다. 이 경우에도 같은 원칙이 적용됩니다. 이전 응답의 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에도 바인딩되므로, 다른 세션이나 정렬 순서에 대해 발급된 커서도 같은 본문을 반환합니다:

The page parameter is not a valid cursor for this request.

messages 엔드포인트의 커서는 또한 워크(walk, 페이지를 한 번 순회하는 과정)가 시작된 지 24시간 후에 만료됩니다. 만료된 커서는 다음을 반환합니다:

The page cursor has expired. Restart the walk without a page parameter; results will reflect the current retention boundary.

첫 번째 본문의 경우, 이전 응답의 수정되지 않은 next_page 값을 그것을 발급한 엔드포인트와 세션으로 다시 보내세요. 만료된 커서의 경우, page 매개변수 없이 다시 시작하세요. 새 워크는 시작 시점에 유효한 보존 경계를 반영하므로, 그 사이에 보존 기간을 지나 만료된 메시지는 더 이상 반환되지 않습니다(로컬 세션 트랜스크립트 검색 참조).

트랜스크립트 페이지가 너무 큼

Type: invalid_request_error

오류 코드: transcript_page_read_limit_exceeded, error.details.error_code에 반환됨

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 없이 세션의 워크(페이지를 한 번 순회하는 과정, 로컬 세션 트랜스크립트 검색 참조)를 다시 시작하고, 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를 반환합니다. 유효한 키라도 scope가 맞지 않으면 403 Forbidden이 반환됩니다.

유효하지 않거나, 비활성화되었거나, 만료된 API 키

Type: authentication_error

API key is invalid.

API key has been deactivated.

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에서, Admin API 키는 Claude Console의 Admin keys 페이지(platform.claude.com/settings/admin-keys)에서 활성화할 수 있습니다. 삭제된 키는 복원할 수 없습니다. 삭제되었거나 만료된 키의 경우, 키 관리 및 교체에 설명된 대로 새 키를 생성하고 통합이 새 키를 사용하도록 업데이트하세요.

403 Forbidden

x-api-key의 키는 유효하지만, 엔드포인트가 허용하는 scope를 가지고 있지 않습니다. 오류 메시지 원문에는 키가 가진 scope(Got:)와 엔드포인트가 허용하는 scope가 나열됩니다. 허용 scope는 나열된 scope 중 하나만 있으면 되는 읽기 엔드포인트에서는 Needed one of:로, 삭제 엔드포인트에서는 Needed:로 표시됩니다. 따라서 Claude Console이나 claude.ai를 다시 확인하지 않아도 키가 가진 scope를 알 수 있습니다. 읽기 엔드포인트의 허용 목록에는 모든 Compliance API 읽기 엔드포인트에 사용할 수 있는 읽기 전용 감사 scope인 read:org_audit도 포함됩니다. Claude Enterprise 키의 scope 선택을 참조하세요. Compliance Access Key의 scope는 생성 후 변경할 수 없으므로, scope 부족 오류의 해결 방법은 모두 기존 키를 수정하는 대신 새 키를 생성하도록 안내합니다. 독립형 Claude Console 조직(상위 조직이 없는 조직)은 Compliance Access Key를 생성할 수 없으므로, Compliance Access Key가 필요한 해결 방법은 적용되지 않습니다. 이러한 조직은 Activity Feed만 쿼리할 수 있습니다.

스코프 부족: Activity Feed

Type: permission_error

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 스코프 없이 생성되었습니다.
• Claude Console Admin API 키(sk-ant-admin01-...)가 조직에 Compliance API가 활성화되지 않은 상태에서 생성되었습니다. Compliance API가 활성화되지 않은 상태에서 생성된 키는 해당 스코프를 가지지 않습니다. Compliance API 설정을 참조하세요.

해결 방법: Compliance Access Key 스코프는 생성 후 변경할 수 없습니다. read:compliance_activities를 포함하는 새 키를 생성하거나, Claude Console Admin API 키를 사용하세요. Admin API 키가 이 스코프를 가지는 조건은 어떤 키가 필요한가요?를 참조하세요.

스코프 부족: 조직 데이터

Type: permission_error

Missing required scopes. Got: ['read:compliance_user_data'] Needed one of: ['read:compliance_org_data', 'read:org_audit']

원인: read:compliance_org_data가 없는 키로 조직, 역할, 그룹 또는 effective-settings 엔드포인트를 호출했습니다. 이 오류에 이르는 일반적인 경로는 두 가지입니다:

• Compliance Access Key(sk-ant-api01-...)가 read:compliance_org_data 스코프 없이 생성되었습니다.
• Claude Console Admin API 키(sk-ant-admin01-...)가 사용되었습니다. Admin API 키는 read:compliance_activities만 가지며 조직 메타데이터를 읽을 수 없습니다.

해결 방법: read:compliance_org_data를 선택하여 새 Compliance Access Key를 생성하세요. Admin API 키는 조직 메타데이터를 읽을 수 없으므로 Compliance Access Key가 필요합니다.

종료된 스코프: 조직 설정

Type: permission_error

Missing required scopes. Got: ['read:compliance_org_settings'] Needed one of: ['read:compliance_org_data', 'read:org_audit']

원인: read:compliance_org_settings 스코프는 2026년 6월 30일에 종료되었습니다. GET /v1/compliance/organizations/{organization_id}/settings는 이제 다른 조직 엔드포인트와 동일한 스코프인 read:compliance_org_data를 요구하며, 종료된 스코프는 더 이상 아무것도 승인하지 않습니다. read:compliance_org_settings만 가진 Compliance Access Key는 종료 이전에는 작동했더라도 settings 엔드포인트에 대한 모든 호출에서 이 오류를 반환합니다. 종료된 스코프는 키를 생성할 때 더 이상 선택하거나 부여할 수 없습니다.

해결 방법: Compliance Access Key 스코프는 생성 후 변경할 수 없습니다. read:compliance_org_data를 선택하여 새 Compliance Access Key를 생성하고, 통합을 새 키를 사용하도록 업데이트한 다음, 이전 키를 삭제하세요. 이미 read:compliance_org_data를 가진 키는 종료의 영향을 받지 않습니다.

스코프 부족: 사용자 데이터

Type: permission_error

Missing required scopes. Got: ['read:compliance_activities'] Needed one of: ['read:compliance_user_data', 'read:org_audit']

원인: read:compliance_user_data가 없는 키로 채팅, 메시지, 파일, 프로젝트, 세션, 조직 사용자 또는 group-members 엔드포인트를 호출했습니다. 이 오류에 이르는 일반적인 경로는 두 가지입니다:

• 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를 부여받을 수 없으므로, 채팅, 파일, 프로젝트, 프로젝트 첨부 파일, 세션, 사용자 또는 group-member 엔드포인트를 호출할 수 없습니다.

해결 방법: claude.ai에서 read:compliance_user_data를 선택하여 생성한 Compliance Access Key를 사용하세요. 요청이 실제로 Activity Feed 전용이어야 한다면, Admin API 키를 대신 GET /v1/compliance/activities로 향하게 하세요.

스코프 부족: 삭제

Type: permission_error

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

원인: delete:compliance_user_data가 없는 Compliance Access Key로 채팅, 파일 또는 프로젝트의 DELETE 엔드포인트를 호출했습니다.

해결 방법: delete:compliance_user_data를 선택하여 새 Compliance Access Key를 생성하세요. 읽기 전용 감사 키가 콘텐츠를 삭제할 수 없도록 삭제 스코프는 read:compliance_user_data와 분리되어 있습니다.

404 Not Found

메시지에 리소스나 리소스 유형이 명시된 404는 경로의 ID가 존재하지 않거나 이미 삭제되었다는 뜻입니다. Compliance API의 삭제는 즉시 영구적으로 적용되므로, 이전에 확인했던 ID에서 404가 반환되면 대개 콘텐츠가 사라진 것입니다. 즉, Compliance API 삭제 호출로 "hard-delete"(영구 삭제)되었거나, 보존 정책에 따라 제거되었거나, 파일 및 아티팩트의 경우 사용자가 claude.ai에서 채팅을 삭제할 때 함께 삭제된 것입니다. 메시지가 Not found뿐인 404는 이와 다릅니다. 이는 요청이 인증되지 않았다(또는 경로가 존재하지 않는다)는 뜻이며, 목록 엔드포인트를 포함한 모든 엔드포인트에서 반환될 수 있습니다. 인증되지 않은 요청을 참조하세요. 세션 엔드포인트에는 두 가지 경우가 더 있습니다. 로컬 세션 엔드포인트는 상위 조직에서 해당 엔드포인트를 사용할 수 없는 동안 (목록 조회를 포함한) 모든 호출에서 별도의 404 메시지인 Local sessions are not available.를 반환합니다. 이 메시지는 세션 ID와 관계없이 반환되며 일시적일 수 있습니다. 로컬 세션을 찾을 수 없음을 참조하세요. 원격 세션 엔드포인트에서는 아직 프로비저닝 중인 세션(status가 pending)에 트랜스크립트가 없으므로, 세션이 시작될 때까지 메시지 엔드포인트가 404를 반환합니다. 원격 세션을 찾을 수 없음을 참조하세요. 각 해결 방법에 나오는 활동 유형 문자열(예: claude_chat_created)은 Activity Feed의 activity_types[] 필터에 전달할 수 있는 값입니다. 지원되는 모든 값은 컴플라이언스 활동 쿼리를 참조하세요.

인증되지 않은 요청

유형: not_found_error

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가 반환됩니다.

해결 방법: x-api-key 헤더에 키를 담아 보내고 키의 접두사를 확인하세요. Compliance API는 sk-ant-api01-... 및 sk-ant-admin01-... 키만 허용합니다. 어떤 키가 필요한가요?를 참조하세요. 헤더와 키가 올바르고 다른 경로는 정상적으로 응답하는데 특정 경로만 계속 Not found를 반환한다면, 해당 경로가 Compliance API 레퍼런스와 일치하는지 확인하세요.

채팅을 찾을 수 없음

Type: not_found_error

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

File not found: 0d3b8f72-6c1e-4a59-b2de-7f4c9a1e5b60

원인: 키로 읽을 수 있는 조직에 해당 파일 ID가 존재하지 않거나, 파일이 삭제되었습니다. claude.ai에서 채팅을 삭제하면 채팅에 첨부된 파일도 함께 삭제되지만, 채팅 자체는 목록에 계속 표시됩니다. 메시지에는 요청에서 보낸 claude_file_... ID가 아니라 내부 UUID로 파일이 표시됩니다. 메타데이터, 콘텐츠, 삭제 엔드포인트가 이 본문을 반환하며, 채팅에 첨부된 파일(claude_file_...)과 프로젝트 파일 모두에 해당합니다.

해결 방법: 최근의 claude_file_uploaded 또는 claude_file_deleted 활동과 대조하세요. 채팅과 함께 삭제된 파일에는 claude_file_deleted 활동이 기록되지 않으므로, 해당 채팅의 claude_chat_deleted 활동도 확인하세요. 파일이 삭제되었다면 바이너리는 더 이상 존재하지 않지만, 활동 기록은 6년의 보존 기간 동안 피드에 남아 있습니다.

생성된 파일 또는 아티팩트를 찾을 수 없음

유형: not_found_error

Generated file not found: 'claude_gen_file_01TbR8wAcCeFhJkLnPqStUvX'

Generated file content not found: 'claude_gen_file_01TbR8wAcCeFhJkLnPqStUvX'

Artifact version not found: 'claude_artifact_version_01KmNpQrSt3UvWxYz5AbCdEfG'

원인: 경로의 ID와 일치하는 도구 생성 파일 또는 아티팩트 버전 중 Compliance API로 읽을 수 있는 항목이 없습니다. 생성된 파일의 메타데이터 엔드포인트는 첫 번째 본문을, 콘텐츠 엔드포인트는 두 번째 본문을 반환하며, 두 아티팩트 엔드포인트는 모두 세 번째 본문을 반환합니다. 생성된 파일과 아티팩트는 자신이 생성된 채팅이 삭제될 때 함께 삭제되며, 사용자가 claude.ai에서 채팅을 삭제하는 경우도 마찬가지입니다.

해결 방법: 채팅 메시지 가져오기를 사용하여 해당 ID가 속한 채팅을 조회하세요. 채팅의 deleted_at 값이 채워져 있거나 claude_chat_deleted 활동에 해당 채팅이 기록되어 있다면 콘텐츠가 사라진 것이므로 대기열에서 ID를 제거하세요. 그렇지 않다면 채팅 메시지의 generated_files 및 artifacts 배열과 대조하여 ID를 확인하세요.

프로젝트를 찾을 수 없음

Type: not_found_error

No project is found with the provided id.

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

No project document found with the provided id.

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

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 포함), 세션이 존재한 적이 없는 경우, 세션에 제로 데이터 보존이 적용되는 경우, 또는 세션의 모든 활동이 해당 세션을 실행한 조직에 적용되는 보존 기간을 지난 경우에 원인을 구분하지 않고 이 하나의 메시지를 반환합니다. 로컬 세션에는 프로비저닝(pending) 상태가 없으므로 Local session not found. 응답에는 일시적인 형태가 없습니다. pending 세션이 시작될 때까지 404를 반환하는 원격 세션을 찾을 수 없음과 비교해 보세요. 올바른 형식의 clls_ 식별자가 아닌 세션 ID는 대신 400 Bad Request를 반환합니다.

목록 엔드포인트를 포함한 로컬 세션 엔드포인트는 엔드포인트 자체를 상위 조직에서 사용할 수 없는 동안 다른 404 메시지인 Local sessions are not available.을 반환합니다. 이 응답은 세션 ID에 의존하지 않으며, 고객 측의 어떤 키, 스코프 또는 설정으로도 바꿀 수 없고, 일시적일 수 있습니다. 두 응답 모두 not_found_error type을 가지며, 메시지 텍스트로 구분합니다.

해결 방법: GET /v1/compliance/apps/sessions/local과 세션 ID를 대조하여 확인하세요. 사용자 머신의 세션을 참조하세요. 세션이 더 이상 목록에 나타나지 않는다면, 콘텐츠가 보존 기간을 지났거나(또는 세션이 더 이상 키가 읽을 수 있는 조직에 없거나) 트랜스크립트를 조회할 수 없는 것이므로 큐에서 ID를 제거하세요. 목록을 포함한 모든 호출이 Local sessions are not available.을 반환한다면, 큐에 있는 세션 ID를 유지하고 다음 예정된 실행에서 재시도하세요. 응답이 지속되면 Anthropic 담당자에게 문의하고 request-id 응답 헤더를 포함하세요.

원격 세션을 찾을 수 없음

Type: not_found_error

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를 반환합니다.

해결 방법: GET /v1/compliance/apps/sessions/remote와 세션 ID 및 status를 대조하여 확인하세요. 클라우드의 세션을 참조하세요. 세션이 pending이면 해당 상태를 벗어난 후 재시도하세요. 세션이 더 이상 목록에 나타나지 않는다면 삭제된 것이며 트랜스크립트를 조회할 수 없습니다.

조직, 역할 또는 그룹을 찾을 수 없음

Type: 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의 최근 조직, 역할 또는 그룹 활동과 대조하세요.

조직 설정을 사용할 수 없음

Type: 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가 아닌 경우, 또는 settings 엔드포인트가 상위 조직에 아직 활성화되지 않은 경우입니다.

해결 방법: 조직 목록과 ID를 대조하여 확인하세요. 정상으로 알려진 조직 ID가 여전히 404를 반환한다면, settings 엔드포인트가 상위 조직에 아직 활성화되지 않은 것입니다. Anthropic 담당자에게 문의하세요.

409 Conflict

요청의 형식이 올바르고 권한도 있지만, 리소스의 현재 상태와 충돌합니다. 본문의 유형은 400 응답에서도 사용하는 invalid_request_error이므로, error.type이 아닌 409 상태 코드로 충돌 여부를 판별하세요.

프로젝트에 연결된 채팅이 있음

유형: invalid_request_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개 요청으로 제한됩니다. 이 "rate limit"(속도 제한)은 상위 조직 아래의 모든 키(Compliance Access Key 및 모든 연결된 조직의 Admin API 키)와 모든 /v1/compliance/* 엔드포인트에 걸쳐 공유되는 하나의 예산입니다. 원격 세션 엔드포인트에는 그 위에 두 번째 요청 예산이 추가로 적용됩니다. 상위 조직이 없는 독립형 Claude Console 조직의 경우, 같은 예산이 조직 자체에 적용되며 해당 조직의 Admin API 키 전체에 걸쳐 공유됩니다. 통합에 더 높은 한도가 필요하면 Anthropic 담당자에게 문의하세요.

한 가지 429는 다릅니다. 매우 큰 세션에서 로컬 세션 메시지 엔드포인트는 대용량 트랜스크립트 읽기로 인한 서버 사용 중을 반환할 수 있는데, 이는 속도 제한이 아니며 조직에 대한 제한도 아닙니다. 이 섹션 끝에 있는 해당 항목에서 이를 식별하는 방법과 대처 방법을 설명합니다.

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."
  }
}

원인: 상위 조직(또는 독립형 Claude Console 조직)이 예산을 공유하는 모든 키에 걸쳐 1분 윈도우 내에 /v1/compliance/*로 600개를 초과하는 요청을 보냈거나, 원격 세션 엔드포인트의 두 번째 요청 예산(이 섹션 뒷부분에서 설명)을 소진했습니다.

해결 방법: retry-after 헤더의 초 수만큼 기다린 후 재시도하세요. 헤더가 없다면(예: 중간 장치에 의해 제거됨) 지수 백오프로 대체하세요(1초에서 시작하여 60초까지 두 배씩 증가). 429에서는 페이지네이션 커서를 전진시키지 마세요. 실패한 요청은 데이터를 반환하지 않았으므로 마지막으로 성공한 페이지의 커서가 여전히 올바릅니다.

인증에 실패한 요청(누락되거나 인식되지 않는 키, 또는 Compliance Access Key나 Admin API 키가 아닌 Claude API 키)은 속도 제한기 이전에 거부되며 할당량을 소비하지 않습니다. 엔드포인트가 요구하는 스코프가 없는 유효한 키는 403이 반환되기 전에 할당량 한 단위를 소비합니다.

로컬 세션 엔드포인트는 공유 한도에만 집계됩니다. 원격 세션 엔드포인트에는 공유 한도에 더해, 공유 한도와 마찬가지로 상위 조직을 기준으로 하는 두 번째 요청 예산도 적용됩니다. 해당 예산에서 발생한 429에는 항상 1인 retry-after 헤더가 포함됩니다(실제 재설정 시간이 아닌 최소 대기 시간). 해당 응답의 anthropic-ratelimit-* 헤더는 이 예산이 아닌 공유 한도를 설명하므로, 429가 반복되면 지수 백오프를 적용하세요. 한 가지 429는 어떤 요청 예산에서도 발생하지 않습니다. 바로 로컬 세션 메시지 엔드포인트만 반환하는 대용량 트랜스크립트 읽기로 인한 서버 사용 중입니다.

Activity Feed를 일정에 따라 폴링한다면, 총 요청 속도(모든 키, 연결된 조직, 동시 워커에 걸쳐)를 공유 한도 아래로 예산을 잡으세요. 한도에 도달하기 전에 속도를 늦추려면 anthropic-ratelimit-requests-remaining을 주시하세요. 윈도우 폴링과 커서 기반 수집 중 선택하는 방법은 컴플라이언스 통합 설계를 참조하세요.

대용량 트랜스크립트 읽기로 인한 서버 사용 중

Type: rate_limit_error

오류 코드: transcript_read_server_busy, error.details.error_code에 반환됨

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초까지 두 배씩 증가). 이 오류가 여러 실행에 걸쳐 계속 반복되면 request-id 응답 헤더를 포함하여 Anthropic 담당자에게 문의하세요.

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으로, 부하가 아닌 조직의 설정이나 암호화 키에 의존합니다. 플랫폼 전체의 재시도 의미론은 오류를 참조하세요.

로컬 세션을 일시적으로 사용할 수 없음

Type: overloaded_error

The local-sessions index is temporarily unavailable. Try again shortly.

Captured content is temporarily unavailable. Try again shortly.

The local-sessions index cannot currently evaluate retention overrides for this page. Try again later.

원인: 로컬 세션 엔드포인트는 이 본문 중 하나와 함께 503을 반환합니다. 세 가지 모두 overloaded_error type을 공유하므로, 이는 이 페이지에서 조건을 구분하기 위해 error.type이 아닌 메시지 텍스트가 필요한 몇 안 되는 오류 중 하나입니다:

• index is temporarily unavailable 본문은 부하 또는 백엔드 상태로 인해 세션 목록을 잠시 사용할 수 없음을 의미합니다. 이는 일시적인 현상입니다.
• Captured content 본문은 현재 세션의 트랜스크립트 콘텐츠를 반환할 수 없음을 의미합니다. 이 역시 대개 일시적입니다. 고객 관리형 암호화 키를 사용하는 조직에서는, 고객 관리형 키로 복호화할 수 없는 콘텐츠가 포함된 모든 페이지에 대해 messages 엔드포인트도 이 본문을 반환합니다. 예를 들어 키를 비활성화, 취소 또는 파기했거나 키에 접근할 수 없는 경우입니다. 이 경우 키를 사용할 수 없는 동안 오류가 계속됩니다. 어느 경우든 메시지 텍스트는 동일하므로, 키가 원인이라는 유일한 신호는 해당 조직에서 오류가 계속 반복된다는 점입니다. 사용할 수 없는 키는 절대 not_captured로 보고되지 않습니다.
• retention overrides 본문은 요청된 범위 내 하나 이상의 세션에 적용되는 보존 또는 데이터 처리 설정을 아직 평가할 수 없음을 의미합니다. retrieve 및 messages 엔드포인트에서는 for this page 대신 for this session으로 표시됩니다. 이는 부하가 아니라 세션을 실행한 조직의 데이터와 설정에 따라 달라지며, 장기간 지속될 수 있습니다.

해결 방법: 각 본문을 다음과 같이 처리하세요:

• 두 개의 Try again shortly. 본문의 경우, 지수 백오프로 재시도하고 page 커서를 전진시키지 마세요. 실패한 요청은 데이터를 반환하지 않았기 때문입니다.
• 고객 관리형 키를 사용하는 조직에 대해 messages 엔드포인트에서 Captured content 본문이 계속 반복된다면, 지속적인 것으로 취급하세요. 해당 조직의 트랜스크립트 순회를 중단하고 키 관리 서비스에서 키의 상태를 확인하세요. 다른 연결된 조직의 트랜스크립트와 모든 곳의 세션 메타데이터는 영향을 받지 않습니다. 이후 실행에서 재시도한다면, messages 페이지 커서는 워크의 첫 페이지 이후 24시간이 지나면 만료되므로 각 세션의 워크를 page 없이 다시 시작하세요.
• Try again later. 본문의 경우, 해소되기를 기다리며 워크를 열어 두지 마세요. 목록 엔드포인트에서는 page 매개변수 없이 다시 시작하여 나중에 재시도하거나(24시간보다 오래된 목록 페이지 토큰은 여전히 허용되지만 현재 보존 경계에 대해 재평가되므로, 대기 중이던 워크는 세션을 건너뛸 수 있습니다), 요청이 성공할 때까지 created_at 윈도우를 좁히고 건너뛴 범위는 이후 실행에서 별도로 내보내세요. 조회 및 messages 엔드포인트에서는 해당 세션 ID를 건너뛰고 나머지 내보내기를 계속한 다음, 이후 실행에서 해당 세션을 재시도하세요. messages 페이지 커서는 워크의 첫 페이지 이후 24시간이 지나면 만료되므로, 해당 세션으로 돌아올 때 page 없이 워크를 다시 시작하세요.

이러한 상황 중 하나라도 여러 실행에 걸쳐 반복되면 request-id 응답 헤더를 포함하여 Anthropic 담당자에게 문의하세요. 고객 관리형 키의 경우, 해당 키를 사용할 수 있는 상태에서도 오류가 계속될 때만 문의하세요.

서비스 전체 장애의 경우 status.anthropic.com을 확인하세요.

다음 단계