Control Zero 오류 코드 레퍼런스

Control Zero SDK와 CLI에서 사용자에게 표시되는 모든 오류에는 안정적인 E#### 코드가 있습니다. 각 코드에는 이 사이트의 전용 페이지가 있으며, 오류 메시지에서 코드를 클릭하면 정식 해결 방법으로 이동합니다.

SDK 코드는 공유 오류 카탈로그(sdks/error-catalog/error_codes.yaml)에 한 번 정의되며 Python과 Node SDK에서 동일한 의미를 가집니다.

코드는 영역별로 구성됩니다:

범위	영역
E1000-E1099	보안 및 시크릿 관리
E1100-E1199	인증 및 등록
E1200-E1299	정책 로드 / 검증 / 번들
E1300-E1399	캐시 및 로컬 디스크 구성
E1400-E1499	네트워크 및 원격 백엔드
E1500-E1599	승인 게이트, 훅 하위 프로세스, 에이전트 통합
E1600-E1699	SDK 런타임 (guard / audit / close)
E1700-E1799	HITL(사람 개입) 승인 및 시크릿
E2000-E2099	자격 증명 유출 탐지
E3000-E3299	플랫폼 백엔드 (API / SSO)
E4000-E4099	거버넌스 게이트웨이

보안 및 시크릿 (E10xx)

• E1001 -- 에이전트 설정 파일에서 API 키가 발견됨
• E1002 -- ~/.controlzero 디렉터리를 누구나 읽을 수 있음
• E1003 -- config.yaml을 누구나 읽을 수 있음
• E1004 -- 셸 기록에서 API 키가 발견됨
• E1005 -- 에이전트 설정 파일을 읽을 수 없음

인증 및 등록 (E11xx)

• E1101 -- API 키가 거부됨 (401)
• E1102 -- 등록 토큰이 만료됨
• E1103 -- API 키를 찾을 수 없음
• E1104 -- API 키 형식이 올바르지 않음

정책 로드 / 검증 / 번들 (E12xx)

• E1201 -- 정책 파일 검증 실패
• E1202 -- 정책 파일을 찾을 수 없음
• E1203 -- 정책 번들 서명 불일치
• E1204 -- 정책 버전 충돌
• E1205 -- 정책 번들 없음, 실패 시 차단(fail-closed) 작동

캐시 및 로컬 디스크 구성 (E13xx)

• E1301 -- 캐시 디렉터리 권한이 잘못됨
• E1302 -- 교체된 키에 대한 오래된 번들
• E1303 -- 감사 로그에 쓸 수 없음

네트워크 및 원격 백엔드 (E14xx)

• E1401 -- 백엔드에 연결할 수 없음
• E1402 -- 백엔드가 5xx를 반환함
• E1403 -- 속도 제한 초과
• E1404 -- TLS 검증 실패
• E1405 -- 현재 플랜에서 사용할 수 없는 기능

승인 게이트 및 훅 하위 프로세스 (E15xx)

• E1500 -- 이 범위에서 승인이 비활성화됨
• E1501 -- 훅 입력이 JSON이 아님
• E1502 -- 훅 시간 초과
• E1503 -- 훅이 잘못된 결정 키를 반환함
• E1504 -- Windows 에이전트 훅 구문 오류

SDK 런타임 (E16xx)

• E1601 -- close() 이후 guard()가 호출됨
• E1602 -- 도구 이름이 표준 어휘에 없음
• E1603 -- 인수 해시 불일치 (결정론적 검사)

HITL 승인 및 시크릿 (E17xx)

승인(사람 개입) 흐름은 Beta이며 호스티드(SaaS) 플랜을 포함한 모든 배포에서 사용할 수 있습니다. 승인은 기본적으로 꺼져 있으며, 관리자가 범위별로 켭니다. 제공 여부는 승인 워크플로를, 활성화 방법은 승인 설정을 참고하세요.

• E1701 -- 승인 요청 시간 초과
• E1702 -- 승인 백엔드에 연결할 수 없음
• E1703 -- 승인 정책 버전 충돌
• E1704 -- 이 조직에는 승인이 구성되지 않음
• E1705 -- 사용 가능한 승인자가 없음
• E1706 -- 요청자 ID가 조직에 없음
• E1707 -- 요청자 ID가 필요함
• E1708 -- 요청자 ID 클레임이 거부됨
• E1709 -- 페이로드에 시크릿 값이 유출됨
• E1710 -- 시크릿 승인 필요
• E1711 -- 시크릿을 찾을 수 없음
• E1712 -- 번들에 더 최신 SDK가 필요함

자격 증명 유출 탐지 (E20xx)

• E2001 -- 도구 출력에서 자격 증명 유출이 탐지됨

플랫폼 백엔드 (E3xxx)

Control Zero 플랫폼 API가 구조화된 오류 본문 { "error": { "code", "reason_code", "request_id", ... } }으로 반환합니다. reason_code가 안정적인 E####입니다. 오류를 로그에서 추적할 수 있도록 지원팀에 request_id를 알려 주세요.

코드	의미
E3000	내부 서버 오류
E3001	요청 검증 실패
E3002	리소스를 찾을 수 없음
E3003	권한 거부
E3004	인증이 필요하거나 실패함
E3005	속도 또는 사용량 제한 초과
E3006	업스트림 종속 서비스를 사용할 수 없음
E3007	상태 충돌 / 이미 존재함
E3008	무결성 / 테넌트 간 위반
E3009	서비스를 사용할 수 없음
E3010	잘못된 형식의 요청
E3011	CSRF 토큰이 없거나 올바르지 않음
E3012	요청 본문이 크기 제한을 초과함
E3200	이 조직에 SSO가 구성되지 않음
E3201	SSO가 구성되어 있지만 올바르지 않음
E3202	ID 공급자에 연결할 수 없음
E3203	SSO state missing, expired, or tampered
E3204	SSO 토큰 / 어설션이 거부됨
E3205	역할 매핑이 없거나 플랜에서 해당 역할을 허용하지 않음
E3206	계정이 정지되었거나 비활성 상태임

거버넌스 게이트웨이 (E4xxx)

거버넌스 게이트웨이가 반환합니다.

영어 원문 -- 번역은 기술 검토 대기 중입니다

Enforcement-path failures fail closed: if the gateway cannot complete its policy / DLP / auth checks it denies the request rather than forwarding it.

코드	의미
E4000	내부 게이트웨이 오류 (비적용 경로)
E4001	Governance evaluation failed; request denied (fail-closed)
E4002	잘못된 형식의 요청
E4003	속도 제한 초과
E4004	인증이 필요하거나 올바르지 않음
E4005	거버넌스 게이트웨이가 초기화되지 않음

발견한 새 오류 보고하기

controlzero doctor가 보고한 코드의 페이지를 찾을 수 없다면 아직 페이지가 게시되지 않은 것입니다. github.com/controlzero/control_zero/issues에 이슈를 열고 전체 오류 메시지와 controlzero env-dump 출력(--show-secrets는 끈 상태)을 포함해 주세요.