오류 봉투(envelope)
오류는 다음 형태와 함께 200이 아닌 상태 코드를 반환합니다:Fail-closed: 오류는 결코 깨끗한 결과가 아닙니다
Guard API는 fail-closed입니다. Guardian이 완전히 분석할 수 없는 요청은 HTTP 오류를 반환합니다 — 탐지 결과가 빈200으로 절대 격하되지 않습니다. 따라서 PASS는 항상 “분석 완료, 아무것도 탐지되지 않음”을 의미하며, 장애가 조용히 우회로 바뀌는 일이 없습니다. Guardian 측 실패는 두 가지 유형으로 나뉩니다:
- 입력 오류(4xx) — 입력 자체를 처리할 수 없는 경우(예: 내용을 추출할 수 없는 손상된 파일).
- 처리 실패(5xx) — 입력은 정상이지만 Guardian이 완료하지 못한 경우(예: AI 모델 호출 실패 또는 타임아웃).
인증 — 401
누락되었거나, 잘못되었거나, 폐기된 API 키는error.details: "API_KEY_INVALID"와 함께 HTTP 401을 반환합니다. X-Starfort-Guard-Api-Key 헤더와 키가 여전히 활성 상태인지 확인하세요. 인증을 참고하세요.
호출을 중단시키는 상태
호출은 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(허용)으로 처리하세요.