> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starfort.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 오류 및 상태

> 오류 응답과 Guard API 호출을 중단시킬 수 있는 플랫폼 상태.

## 오류 봉투(envelope)

오류는 다음 형태와 함께 200이 아닌 상태 코드를 반환합니다:

```json theme={null}
{
  "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` 헤더와 키가 여전히 활성 상태인지 확인하세요. [인증](/ko/v1.2/api/authentication)을 참고하세요.

## 호출을 중단시키는 상태

호출은 Guardian이 실행되기 전에 사전 검증을 거칩니다. 다음은 호출을 중단시킬 수 있는 상태이며, 검사되는 순서대로 나열되어 있습니다:

| 상태                            | 발생한 일                                                                           | 조치                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Auth failure**              | 키가 누락되었거나, 찾을 수 없거나, 폐기되었습니다.                                                   | **401**(위)을 반환합니다.                                                                                            |
| **API not found**             | 키와 일치하는 API가 없습니다.                                                              | 올바른 키를 사용하고 있는지 확인하세요.                                                                                        |
| **API key inactive**          | 관리자가 키를 비활성화했습니다.                                                               | 다시 활성화하거나 다른 키를 사용하세요. [API 키 관리](/ko/v1.2/admin/api-keys)를 참고하세요.                                            |
| **Kill Switch active**        | 관리자가 조직, 프로젝트, 또는 Guardian에 [Kill Switch](/ko/v1.2/admin/kill-switch)를 활성화했습니다. | 트래픽이 의도적으로 차단된 상태입니다. 비활성화될 때까지 기다리세요.                                                                        |
| **Unsupported `processType`** | 값이 Guardian이 선언한 것이 아닙니다.                                                       | 지원되는 프로세스 타입을 사용하세요. 오류 메시지에 목록이 표시됩니다.                                                                       |
| **Input Type not enabled**    | 콘텐츠 파트의 타입이 Guardian에서 활성화되지 않았습니다.                                             | Guardian에서 활성화하거나 해당 파트를 보내지 마세요. (파일 파트는 BLOCK 처리 방식에서만 여기서 실패합니다 — [멀티모달](/ko/v1.2/api/multimodal)을 참고하세요.) |
| **Limit exceeded**            | 텍스트 길이 또는 파일 크기가 Guardian의 한도를 초과했습니다.                                          | 페이로드를 줄이세요.                                                                                                   |
| **Guardian failure**          | Guardian 엔드포인트에 도달할 수 없거나 오류가 발생했습니다.                                           | 백오프를 적용해 재시도하세요.                                                                                              |

**inactive**와 **Kill Switch** 응답은 차단이 어디(조직 / 프로젝트 / Guardian)에서 왔는지 **의도적으로 드러내지 않습니다** — 이는 리소스 열거(enumeration)를 방지하기 위함입니다. 위치는 감사 로그에만 기록됩니다.

<Note>
  위 상태에 대한 정확한 `error.code` 값과 HTTP 상태는 배포 환경에 따라 다를 수 있습니다. 위의 **401** 인증 응답이 안정적인 계약입니다. 항상 HTTP 상태를 먼저 분기한 다음 `error.details`로 분기하세요.
</Note>

## 트레이싱되는 항목

키가 활성 상태로 확인된 이후의 실패 — 미지원 `processType`, Input Type 불일치, 한도 위반, Guardian 실패 — 는 [Opticon 트레이스](/ko/v1.2/admin/monitoring-opticon)로 **기록됩니다**(오류 정보 + 입력 메타데이터. 단, 메시지 본문이나 파일 내용은 제외). 그 이전 상태 — auth failure, API not found, inactive key, Kill Switch — 는 트레이싱되지 **않습니다**. 이는 별도 로그에서 처리되는 보안/거버넌스 이벤트입니다.

## 권장 처리 방식

<Steps>
  <Step title="HTTP 상태 확인">200 = 평가됨; 4xx/5xx = 평가되지 않음.</Step>
  <Step title="200일 때 `action`으로 분기">PASS / MASK / BLOCK — [응답 형식](/ko/v1.2/api/response-format)을 참고하세요.</Step>
  <Step title="오류일 때 `error.details` 검사">위험 관리 방침에 따라 fail closed(차단) 또는 fail open(허용)으로 처리하세요.</Step>
</Steps>