메인 콘텐츠로 건너뛰기

​
오류 봉투(envelope)

오류는 다음 형태와 함께 200이 아닌 상태 코드를 반환합니다: 
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials (getApiGuardGate)",
    "details": "API_KEY_INVALID"
  }
}

​
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이 실행되기 전에 사전 검증을 거칩니다. 다음은 호출을 중단시킬 수 있는 상태이며, 검사되는 순서대로 나열되어 있습니다:
상태발생한 일조치
Auth failure키가 누락되었거나, 찾을 수 없거나, 폐기되었습니다.401(위)을 반환합니다.
API not found키와 일치하는 API가 없습니다.올바른 키를 사용하고 있는지 확인하세요.
API key inactive관리자가 키를 비활성화했습니다.다시 활성화하거나 다른 키를 사용하세요. API 키 관리를 참고하세요.
Kill Switch active관리자가 조직, 프로젝트, 또는 Guardian에 Kill Switch를 활성화했습니다.트래픽이 의도적으로 차단된 상태입니다. 비활성화될 때까지 기다리세요.
Unsupported processType값이 Guardian이 선언한 것이 아닙니다.지원되는 프로세스 타입을 사용하세요. 오류 메시지에 목록이 표시됩니다.
Input Type not enabled콘텐츠 파트의 타입이 Guardian에서 활성화되지 않았습니다.Guardian에서 활성화하거나 해당 파트를 보내지 마세요. (파일 파트는 BLOCK 처리 방식에서만 여기서 실패합니다 — 멀티모달을 참고하세요.)
Limit exceeded텍스트 길이 또는 파일 크기가 Guardian의 한도를 초과했습니다.페이로드를 줄이세요.
Guardian failureGuardian 엔드포인트에 도달할 수 없거나 오류가 발생했습니다.백오프를 적용해 재시도하세요.
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(허용)으로 처리하세요.