오류 봉투(envelope)
오류는 다음 형태와 함께 200이 아닌 상태 코드를 반환합니다:이 페이지는 동기 Guard API의 오류를 다룹니다. S3 연계 비식별화 배치의 오류 규약 — 접수 시점 HTTP 오류와 처리 시점 작업 실패(
error.code)의 구분 — 은 배치 오류를 참고하세요.Fail-closed: 오류는 결코 깨끗한 결과가 아닙니다
Guard API는 fail-closed입니다. Guardian이 완전히 분석할 수 없는 요청은 HTTP 오류를 반환합니다 — 탐지 결과가 빈200으로 절대 격하되지 않습니다. 따라서 PASS는 항상 “분석 완료, 아무것도 탐지되지 않음”을 의미하며, 장애가 조용히 우회로 바뀌는 일이 없습니다. Guardian 측 실패는 두 가지 유형으로 나뉩니다:
- 입력 오류(4xx) — 입력 자체를 처리할 수 없는 경우(예: 내용을 추출할 수 없는 손상된 파일).
- 처리 실패(5xx) — 입력은 정상이지만 Guardian이 완료하지 못한 경우(예: AI 모델 호출 실패 또는 타임아웃).
트레이스 기록 실패 (Fail-Closed 프로젝트)
v1.3부터 프로젝트는 Opticon 페일세이프 정책을 Fail-Closed로 설정할 수 있습니다. 요청이 분석은 됐지만 트레이스 기록이 끝내 실패하면, 기록 없이 통과하는 대신 요청이 BLOCK으로 강등됩니다. 기록 시도는 제한적(시간·재시도 상한)이므로 Opticon 장애는 지연 증가와 차단으로 나타날 뿐, 응답이 매달리지는 않습니다. 기본값인 Fail-Open에서는 호출자 입장에서 달라지는 것이 없습니다 — 판정은 그대로 반환되고 기록만 유실됩니다.인증 — 401
누락되었거나, 잘못되었거나, 폐기된 API 키는error.details: "API_KEY_INVALID"와 함께 HTTP 401을 반환합니다. X-Starfort-Guard-Api-Key 헤더와 키가 여전히 활성 상태인지 확인하세요. 인증을 참고하세요.
호출을 중단시키는 상태
호출은 먼저 게이트웨이의 사전 검증(인증 · 키 상태 · Kill Switch ·processType)을 거칩니다. 콘텐츠에 대한 검사 정책 — 미지원 파일 처리와 검사 한도(텍스트 길이 · 파일 크기) — 은 v1.4부터 Guardian이 단일 지점에서 강제하며, 최상위 입력뿐 아니라 파일에서 추출된 텍스트와 아카이브 내부 멤버에도 같은 규칙이 적용됩니다. 다음은 호출을 중단시킬 수 있는 상태이며, 검사되는 순서대로 나열되어 있습니다:
inactive와 Kill Switch 응답은 차단이 어디(조직 / 프로젝트 / Guardian)에서 왔는지 의도적으로 드러내지 않습니다 — 이는 리소스 열거(enumeration)를 방지하기 위함입니다. 위치는 감사 로그에만 기록됩니다.
위 상태에 대한 정확한
error.code 값과 HTTP 상태는 배포 환경에 따라 다를 수 있습니다. 위의 401 인증 응답이 안정적인 계약입니다. 항상 HTTP 상태를 먼저 분기한 다음 error.details로 분기하세요.트레이싱되는 항목
키가 활성 상태로 확인된 이후의 실패 — 미지원processType, Input Type 불일치, 한도 위반, Guardian 실패 — 는 Opticon 트레이스로 기록됩니다(오류 정보 + 입력 메타데이터. 단, 메시지 본문이나 파일 내용은 제외). 그 이전 상태 — auth failure, API not found, inactive key, Kill Switch — 는 트레이싱되지 않습니다. 이는 별도 로그에서 처리되는 보안/거버넌스 이벤트입니다.
권장 처리 방식
1
HTTP 상태 확인
200 = 평가됨; 4xx/5xx = 평가되지 않음.
2
200일 때 `action`으로 분기
PASS / MASK / BLOCK — 응답 형식을 참고하세요.
3
오류일 때 `error.details` 검사
위험 관리 방침에 따라 fail closed(차단) 또는 fail open(허용)으로 처리하세요.