Compliance API 오류 처리

이 페이지는 문서화된 각 Compliance API 엔드포인트가 반환하는 응답 메시지, 원인 및 해결 방법을 나열합니다.

Compliance API는 나머지 Anthropic 오류 형식과 일관된 오류 형식으로 오류를 반환합니다. 즉, 2xx가 아닌 상태 코드, request-id 응답 헤더, 그리고 type과 message를 포함하는 error 객체가 있는 JSON 본문입니다. 지원팀에 에스컬레이션할 때는 request-id 헤더 값을 포함하세요.

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

메시지 문자열이 아닌 error.type으로 매칭하세요. 메시지는 런북에 복사할 수 있을 만큼 안정적이지만 시간이 지나면서 문구가 변경될 수 있습니다. 반면 type 값은 API 계약의 일부입니다.

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

400 Bad Request

요청이 구문적으로는 유효하지만 서버가 거부한 매개변수를 포함하고 있습니다. 매개변수를 수정하고 재시도하세요.

잘못된 타임스탬프 형식

Type: 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)을 datetime으로 파싱할 수 없습니다. 메시지는 실패한 매개변수의 이름을 명시하고 전송된 값을 그대로 표시합니다.

해결 방법: 시간과 시간대를 포함한 완전한 RFC 3339 타임스탬프를 보내세요. 예: 2024-03-01T00:00:00Z 또는 2024-03-01T00:00:00+00:00.

잘못된 limit

Type: invalid_request_error

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

원인: limit 쿼리 매개변수가 허용 범위를 벗어났습니다. 메시지에 명시된 경계값은 호출된 특정 엔드포인트의 최댓값을 반영합니다.

해결 방법: 엔드포인트가 허용하는 범위 내의 limit을 보내세요. 각 목록 엔드포인트는 고유한 limit 범위를 가지고 있습니다. 해당 Compliance API 레퍼런스 페이지의 매개변수 제약 조건을 참조하세요.

잘못된 페이지네이션 ID

Type: invalid_request_error

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

원인: after_id 또는 before_id 커서를 불투명 커서로 디코딩하거나 activity ID로 파싱할 수 없습니다.

해결 방법: 페이지네이션 커서를 불투명 문자열로 취급하세요. 항상 이전 페이지에서 반환된 first_id 또는 last_id 값을 복사하고, has_more가 false일 때 중단하세요. 객체 ID로부터 커서를 구성하지 마세요.

디렉터리 및 프로젝트 엔드포인트(사용자, 역할, 역할 권한, 그룹, 그룹 멤버, 프로젝트, 프로젝트 첨부 파일)는 after_id와 before_id 대신 불투명한 page 토큰으로 페이지네이션합니다. 동일한 조언이 적용됩니다. 이전 응답의 next_page 값을 변경 없이 전달하고, has_more가 false일 때 중단하세요. 잘못된 형식의 page 토큰은 잘못된 형식의 after_id 또는 before_id와 동일한 400 invalid_request_error를 반환합니다.

401 Unauthorized

x-api-key 헤더가 누락되었거나 알려진 키와 일치하지 않습니다. 잘못된 스코프를 가진 유효한 키는 대신 403 Forbidden을 반환합니다.

잘못된 API 키

Type: 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

Type: 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 스코프 없이 생성되었습니다.
• Claude Console Admin API 키(sk-ant-admin01-...)가 조직에 대해 Compliance API가 활성화되기 전에 생성되었습니다. 활성화 전에 생성된 키는 이 스코프를 가지지 않습니다. 활성화 후: Claude Console 조직을 참조하세요.

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

스코프 부족: 조직 데이터

Type: 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 스코프 없이 생성되었습니다.
• 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_activities'] Needed: ['read:compliance_user_data']

원인: read:compliance_user_data가 없는 키로 채팅, 메시지, 파일, 프로젝트, 조직 사용자 또는 그룹 멤버 엔드포인트를 호출했습니다. 이 오류가 발생하는 일반적인 경로는 두 가지입니다.

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

해결 방법: 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

엔드포인트는 확인되었지만 리소스 ID가 존재하지 않거나 이미 삭제되었습니다. Compliance API 삭제는 즉시 영구적으로 적용되므로, 이전에 알려진 ID에 대한 404는 일반적으로 콘텐츠가 Compliance API 삭제 호출을 통해 하드 삭제되었거나 보존 정책에 의해 제거되었음을 의미합니다. 각 해결 방법에서 인용된 activity-type 문자열(예: claude_chat_created)은 Activity Feed activity_types[] 필터에 전달할 수 있는 값입니다. 지원되는 모든 값은 컴플라이언스 활동 쿼리를 참조하세요.

채팅을 찾을 수 없음

Type: not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

원인: 경로의 채팅 ID가 Compliance API를 통해 읽을 수 있는 채팅과 일치하지 않습니다. 채팅이 이전 Compliance API 호출을 통해 하드 삭제되었거나 조직의 보존 정책에 의해 제거되었을 수 있으며, 또는 호출 키가 읽을 수 없는 조직에 속할 수 있습니다. 사용자가 claude.ai에서 소프트 삭제한 채팅은 404를 반환하지 않습니다. 이러한 채팅은 deleted_at이 채워진 상태로 계속 읽을 수 있습니다.

해결 방법: 최근 claude_chat_created 또는 claude_chat_viewed 활동과 채팅 ID를 대조하여 확인하세요. 활동이 최근이고 읽기가 여전히 실패한다면, 채팅이 하드 삭제되었거나(이 API를 통해 또는 보존 정책 만료로 인해) 키의 스코프 밖에 있는 조직에 속합니다.

파일을 찾을 수 없음

Type: 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년 보존 기간 동안 피드에 남아 있습니다.

프로젝트를 찾을 수 없음

Type: not_found_error

No project is found with the provided id.

원인: 프로젝트 ID가 존재하지 않거나 삭제되었습니다.

해결 방법: 최근 claude_project_created 또는 claude_project_deleted 활동과 대조하세요. Activity Feed는 프로젝트 자체가 사라진 후에도 프로젝트의 라이프사이클 이벤트를 계속 노출합니다.

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

Type: 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 활동 레코드를 통해 조회하세요.

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

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

409 Conflict

요청이 올바른 형식이고 권한이 있지만 리소스의 현재 상태와 충돌합니다.

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

Type: 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[] 값이 필요합니다. 조직 사용자 나열을 통해 ID를 열거하세요), DELETE /v1/compliance/apps/chats/{claude_chat_id}로 각각을 삭제한 다음 프로젝트 삭제를 재시도하세요.

429 Too Many Requests

Compliance API에 대한 요청은 상위 조직당 분당 600개 요청으로 제한됩니다. 이 제한은 상위 조직 아래의 모든 키(Compliance Access Key 및 연결된 모든 조직의 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."
  }
}

원인: 상위 조직이 모든 키와 연결된 조직을 통틀어 1분 윈도우 내에 /v1/compliance/*로 600개 이상의 요청을 보냈습니다.

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

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

일정에 따라 Activity Feed를 폴링하는 경우, 총 요청 속도(모든 키, 연결된 조직 및 동시 워커 전체)를 상위 조직 제한 미만으로 예산을 책정하세요. 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 응답에도 동일하게 적용됩니다. 플랫폼 전체 재시도 의미 체계는 오류를 참조하세요.

서비스 전체 인시던트의 경우 status.anthropic.com을 확인하세요.

최대 응답 크기 초과

Type: 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 활동 유형을 통해 멤버십 이벤트를 노출하므로, 다음 폴링 간격을 기다리는 대신 즉시 재나열을 트리거하는 데 사용할 수 있습니다.

다음 단계