Compliance API 오류 처리

이 페이지는 HTTP 상태 코드별로 일반적인 Compliance API 오류 응답과 각각의 원인·해결책을 나열해 드릴게요.

Compliance API를 활성화하려면 Compliance API 설정을 참고하세요.

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으로 매칭하세요. 메시지는 런북에 복사하기에 충분히 안정적이지만 시간이 지나며 바뀔 수 있고, 상태 코드와 유형 값은 API 계약의 일부예요. 상태 코드와 유형을 공유하는 몇몇 응답은 메시지로 구분되며, 각각이 적용되는 곳에서 별도로 설명해요.

다음 표는 재시도 여부를 한눈에 알려줘요. 뒤의 각 섹션은 그대로의 오류 본문과 해결책을 보여줘요.

상태	재시도?	시점
400 Bad Request	아니요	요청을 고치거나, 메시지가 활성화되지 않았다고 하면 Compliance API를 활성화한 뒤 다시 보내세요.
401 Unauthorized	아니요	키가 인식되지 않거나, 비활성화되었거나, 만료됨. 다시 활성화하거나 교체한 뒤 다시 보내세요.
403 Forbidden	아니요	빠진 범위를 추가하거나 올바른 키 유형을 사용한 뒤 다시 보내세요.
404 Not Found	보통 아니요	리소스를 명명하는 메시지는 삭제되었거나 존재하지 않았다는 뜻. 큐에서 제거하세요. 순수 메시지 `Not found`는 리소스가 사라진 것이 아니라 요청이 인증되지 않았음을(또는 경로가 존재하지 않음을) 의미합니다. 요청이 인증되지 않음 참고. 세션 엔드포인트는 두 가지를 더 추가해요: 로컬 세션 엔드포인트에서 `Local sessions are not available.` 메시지(목록을 포함해 모든 호출에서 반환)는 세션이 사라진 것이 아니라 엔드포인트가 현재 상위 조직에 사용 불가함을 의미합니다. 대기 중인 ID를 유지하고 로컬 세션을 찾을 수 없음을 참고하세요. 아직 `pending` 상태인 원격 세션은 시작할 때까지 messages 엔드포인트에서 404가 됩니다. 원격 세션을 찾을 수 없음 참고.
409 Conflict	아니요	요청이 리소스의 현재 상태와 충돌. 충돌을 해결하고(예: 하위 리소스 분리) 다시 시도하세요.
429 Too Many Requests	예, `retry-after` 이후	`retry-after`의 초를 기다린 뒤 재시도하세요. 커서는 전진시키지 마세요.
500 Internal Server Error	`x-should-retry`에 따라 다름	재시도 전에 `x-should-retry` 응답 헤더를 확인하세요.
502, 503, 504, 529	예, 백오프 사용	일시적. 지수 백오프로 재시도. 예외: 일부 로컬 세션 503은 일시적이지 않음. 로컬 세션 일시적 사용 불가 참고.

출처: 문서

본문

400 Bad Request

요청이 구문적으로 유효했지만 서버가 매개변수를 거부했거나 조직에 Compliance API가 활성화되지 않았어요. 메시지에 명명된 원인을 고치고 다시 보내세요.

Compliance API가 활성화되지 않음

유형: 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[] 값은 Compliance 활동 조회 참고.

로컬 세션 목록(GET /v1/compliance/apps/sessions/local)은 두 시간 경계가 모두 제공되고 created_at.lt가 created_at.gte보다 엄격히 이후가 아닐 때도 400 invalid_request_error를 반환해요. 본문은:

created_at.lt must be strictly after created_at.gte.

created_at.gte보다 늦은 created_at.lt를 보내거나 경계 중 하나를 생략하세요.

세션 기록 엔드포인트(GET /v1/compliance/apps/sessions/local/{session_id}/messages와 GET /v1/compliance/apps/sessions/remote/{session_id}/messages)는 잘림 매개변수를 같은 방식으로 검증해요. tool_use_input_max_bytes와 tool_result_max_bytes는 각각 양수 바이트 수 또는 -1(서버 최대값)을 받으므로 0 같은 값은 같은 400 invalid_request_error를 반환해요.

잘못된 페이지네이션 커서

유형: invalid_request_error

Invalid activity_id format: 'activity_invalid123'

Invalid pagination cursor for 'after_id'

원인: 페이지네이션 커서를 디코딩할 수 없었어요. Activity Feed에서 API가 발급한 커서도 정상적인 활동 ID도 아닌 after_id·before_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 매개변수 없이 다시 시작하세요. 새 순회는 시작 시점에 적용되는 보존 경계를 반영하므로 그 사이 보존 기간을 지난 메시지는 더 이상 반환되지 않아요(로컬 세션 기록 조회 참고).

401 Unauthorized

요청이 인증되지 않는 Compliance Access Key(sk-...) 또는 Admin API 키(sk-...)를 담았어요. 키 없이 보내거나 다른 유형의 키를 담은 요청은 조직 설정을 제외한 모든 엔드포인트에서 대신 404 Not Found를 반환하고, 잘못된 범위를 가진 유효한 키는 403 Forbidden을 반환해요.

잘못되었거나 비활성화되었거나 만료된 API 키

유형: 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 > Settings > Admin keys에서. 삭제된 키는 복원할 수 없어요. 삭제되거나 만료된 키는 키 관리 및 교체에 설명된 대로 새 키를 만들고 통합이 이를 사용하도록 업데이트하세요.

403 Forbidden

x-api-key의 키는 유효하지만 엔드포인트가 허용하는 범위를 담지 않았어요. 그대로의 메시지는 키가 가진 범위(Got:)와 엔드포인트가 허용하는 범위(읽기 엔드포인트의 Needed one of: — 나열된 임의의 하나면 충분, 삭제 엔드포인트의 Needed:)를 나열해요. 그래서 Claude Console이나 claude.ai를 다시 확인하지 않고 키가 무엇을 가졌는지 확인할 수 있어요. 읽기 엔드포인트에서 허용 목록은 모든 Compliance API 읽기 엔드포인트를 다루는 읽기 전용 감사 범위인 read:org_audit도 포함해요. Claude Enterprise 키의 범위 선택 참고. Compliance Access Key 범위는 생성 후 변경할 수 없으므로 각 범위 부족 해결책은 기존 키를 편집하는 대신 새 키를 만들도록 안내해요. 상위 조직이 없는 독립 Claude Console 조직은 Compliance Access Key를 만들 수 없으므로 하나가 필요한 해결책은 적용되지 않고 Activity Feed만 조회할 수 있어요.

범위 부족: Activity Feed

유형: 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를 호출했어요. 이 오류로 가는 두 가지 흔한 경로가 있어요:

read:compliance_activities 범위 없이 만들어진 Compliance Access Key(sk-...).
조직에 Compliance API가 활성화되지 않은 동안 만들어진 Claude Console Admin API 키(sk-...). Compliance API가 활성화되지 않은 동안 만든 키는 범위를 담지 않아요. Compliance API 설정 참고.

해결책: Compliance Access Key 범위는 생성 후 변경할 수 없어요. read:compliance_activities를 포함한 새 키를 만들거나 Claude Console Admin API 키를 사용하세요. Admin API 키가 이 범위를 담는 조건은 어떤 키가 필요하나요? 참고.

범위 부족: 조직 데이터

유형: permission_error

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

원인: read:compliance_org_data가 없는 키로 조직, 역할, 그룹 또는 유효 설정 엔드포인트를 호출했어요. 두 가지 흔한 경로가 있어요:

read:compliance_org_data 범위 없이 만들어진 Compliance Access Key(sk-...).
사용된 Claude Console Admin API 키(sk-...). Admin API 키는 read:compliance_activities만 담으며 조직 메타데이터를 읽을 수 없어요.

해결책: read:compliance_org_data를 선택한 새 Compliance Access Key 만들기. Admin API 키는 조직 메타데이터를 읽을 수 없으므로 Compliance Access Key가 필요해요.

은퇴한 범위: 조직 설정

유형: 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를 담은 키는 은퇴의 영향을 받지 않아요.

범위 부족: 사용자 데이터

유형: permission_error

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

원인: read:compliance_user_data가 없는 키로 채팅, 메시지, 파일, 프로젝트, 세션, 조직 사용자 또는 그룹 구성원 엔드포인트를 호출했어요. 두 가지 흔한 경로가 있어요:

read:compliance_user_data 범위 없이 만들어진 Compliance Access Key(sk-...).
사용된 Claude Console Admin API 키(sk-...). Admin API 키는 read:compliance_activities만 담으며 read:compliance_user_data를 부여받을 수 없으므로 채팅·파일·프로젝트·프로젝트 첨부·세션·사용자·그룹 구성원 엔드포인트를 호출할 수 없어요.

해결책: read:compliance_user_data를 선택한 claude.ai에서 만든 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 엔드포인트를 호출했어요.

해결책: delete:compliance_user_data를 선택한 새 Compliance Access Key 만들기. 삭제 범위는 read:compliance_user_data와 분리되어 있어 읽기 전용 감사 키가 콘텐츠를 삭제할 수 없어요.

404 Not Found

리소스나 리소스 유형을 명명하는 메시지의 404는 경로의 ID가 존재하지 않거나 이미 삭제됐다는 뜻이에요. Compliance API 삭제는 즉시·영구적이므로 이전에 알려진 ID의 404는 보통 콘텐츠가 사라졌다는 뜻이에요. Compliance API 삭제 호출로 하드 삭제되거나 보존 정책으로 제거되거나, 파일·아티팩트의 경우 claude.ai의 사용자가 채팅과 함께 삭제됨. 순수 메시지 Not found의 404는 다르게요: 요청이 인증되지 않았거나(또는 경로가 존재하지 않음) 어떤 엔드포인트든 목록 엔드포인트를 포함해 반환할 수 있어요. 요청이 인증되지 않음 참고. 세션 엔드포인트는 두 경우를 추가해요. 로컬 세션 엔드포인트에서 별도의 404 메시지 Local sessions are not available.은 엔드포인트가 상위 조직에 사용 불가한 동안 (목록을 포함해) 모든 호출에서 반환돼요. 세션 ID와 무관하며 일시적일 수 있어요. 로컬 세션을 찾을 수 없음 참고. 원격 세션 엔드포인트에서 아직 프로비저닝 중인 세션(pending 상태)은 아직 기록이 없으므로, messages 엔드포인트는 세션이 시작할 때까지 404가 됩니다. 원격 세션을 찾을 수 없음 참고. 각 해결책에 인용된 활동 유형 문자열(예: claude_chat_created)은 Activity Feed activity_types[] 필터에 전달할 수 있는 값이에요. 지원되는 모든 값은 Compliance 활동 조회 참고.

요청이 인증되지 않음

유형: not_found_error

Not found

원인: 요청이 Compliance API가 받아들이는 자격 증명을 담지 않았어요: API 키가 보내지지 않았거나, 키가 Compliance Access Key(sk-...)나 Admin API 키(sk-...)가 아님(예: Claude API 키(sk-...)). 상태·유형·메시지는 존재하지 않는 경로와 같으며 엔드포인트나 리소스 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-compliance-access-...(Compliance Access Key)와 sk-ant-admin...(Admin API 키)만 받아요. 어떤 키가 필요하나요? 참고. 헤더와 키가 맞는데도 한 경로만 Not found를 반환하고 다른 경로는 성공한다면 Compliance API 참조에 대해 그 경로를 확인하세요.

채팅을 찾을 수 없음

유형: 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 또는 보존 정책 만료로) 키 범위 밖의 조직에 속한다는 뜻이에요.

파일을 찾을 수 없음

유형: 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를 확인하세요.

프로젝트를 찾을 수 없음

유형: 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는 프로젝트 자체가 사라진 후에도 프로젝트의 수명 주기 이벤트를 계속 노출해요.

프로젝트 문서를 찾을 수 없음

유형: 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 활동 기록으로 조회하세요.

로컬 세션을 찾을 수 없음

유형: 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 포함), 세션이 존재한 적 없을 때, 세션에 제로 데이터 보존이 적용 중일 때, 또는 세션의 모든 활동이 실행한 조직에 적용되는 보존 기간을 지났을 때 이 하나의 메시지를 원인 구분 없이 반환해요. Local session not found. 응답에는 일시적 형태가 없어요. 로컬 세션은 프로비저닝(pending) 상태가 없기 때문이에요. pending 세션이 시작할 때까지 404가 되는 원격 세션을 찾을 수 없음과 비교하세요. 정상적인 clls_ 식별자가 아닌 세션 ID는 대신 400 Bad Request를 반환해요.

로컬 세션 엔드포인트(목록 엔드포인트 포함)는 엔드포인트 자체가 상위 조직에 사용 불가한 동안 Local sessions are not available.이라는 다른 404 메시지를 반환해요. 그 응답은 세션 ID와 무관하고 어떤 고객 측 키·범위·설정으로도 바뀌지 않으며 일시적일 수 있어요. 두 응답 모두 not_found_error 유형을 담아요. 메시지 텍스트가 둘을 구분해줘요.

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

원격 세션을 찾을 수 없음

유형: 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이면 그 상태를 벗어난 뒤 재시도하세요. 세션이 목록에 더 이상 나타나지 않으면 삭제된 것이고 기록을 조회할 수 없어요.

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

유형: 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가 아니거나, 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회 요청으로 제한돼요. 한도는 상위 조직 아래 모든 키(Compliance Access Key와 모든 연결 조직의 Admin API 키)와 모든 /v1/compliance/* 엔드포인트에 걸쳐 공유되는 하나의 예산이에요. 원격 세션 엔드포인트는 추가로 두 번째 요청 예산을 담아요. 상위 조직이 없는 독립 Claude Console 조직은 같은 예산이 조직 자체에 적용되고 Admin API 키 간에 공유돼요. 통합이 더 높은 한도를 필요로 하면 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."
  }
}

원인: 상위 조직(또는 독립 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가 반복되면 지수 백오프하세요.

활동 피드를 예정대로 폴링한다면 집계 요청 속도(모든 키, 연결 조직, 동시 워커에 걸쳐)를 공유 한도 아래로 예산하세요. 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 응답에도 동일하게 적용돼요. 예외는 다음에 설명하는, 부하가 아니라 조직 설정이나 암호화 키에 의존하는 소수의 로컬 세션 503이에요. 플랫폼 전반 재시도 의미는 Errors 참고.

로컬 세션 일시적 사용 불가

유형: 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 유형을 공유하므로, 이 페이지에서 error.type이 아니라 메시지 텍스트로 상황을 구분해야 하는 몇 안 되는 오류 중 하나예요:

index is temporarily unavailable 본문은 부하나 백엔드 상태 때문에 세션 목록이 잠시 사용 불가함을 의미해요. 일시적이에요.
Captured content 본문은 세션의 기록 콘텐츠를 지금 반환할 수 없음을 의미해요. 이것도 보통 일시적이에요. 고객 관리 암호화 키를 사용하는 조직에서 messages 엔드포인트는 키가 복호화할 수 없는 콘텐츠를 담은 모든 페이지에 대해 이 본문을 반환해요. 예를 들어 키를 비활성화·철회·파괴했거나 키에 도달할 수 없을 때. 그 경우 오류는 키를 사용할 수 없는 동안 지속돼요. 메시지 텍스트는 어느 쪽이든 같으므로 키가 원인인 유일한 신호는 그 조직에 오류가 계속 반복된다는 것이에요. 사용 불가능한 키는 결코 not_captured로 보고되지 않아요.
retention overrides 본문은 요청 범위의 하나 이상의 세션에 적용되는 보존·데이터 처리 설정을 아직 평가할 수 없음을 의미해요. 조회·messages 엔드포인트에서는 for this page 대신 for this session으로 읽혀요. 세션을 실행한 조직의 데이터와 설정에 의존하며 부하가 아니라, 긴 기간 지속될 수 있어요.

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

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

이 조건 중 어떤 것이든 실행에 걸쳐 반복되면 Anthropic 담당자에게 연락하고 request-id 응답 헤더를 포함하세요. 고객 관리 키의 경우 그 키가 사용 가능한 동안에도 오류가 계속될 때만 이렇게 하세요.

서비스 전반 사고는 status.anthropic.com을 확인하세요.

다음 단계

Compliance API FAQ — 이동 — 접근·범위·보존·통합에 대한 일반적인 질문.
Errors — 이동 — 플랫폼 전반 오류 카탈로그와 재시도 의미.

Compliance API 오류 처리