> ## 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.

# 배치 오류

> Starfort 배치 비식별화 API의 오류 계약. 인입 시점 HTTP 오류와 처리 시점 error.code로 인한 작업 실패의 의미와 대응을 설명합니다 (Starfort v1.4 문서)

배치의 오류는 발생 시점에 따라 두 층으로 나뉩니다:

* **요청 · 접수 시점** — 접수가 거부되어 **작업이 만들어지지 않습니다**. HTTP 오류 응답으로 즉시 반환됩니다.
* **처리 시점** — 접수는 성공했으나 검사를 완수하지 못해 작업이 `FAILED`로 확정됩니다. 사유는 [작업 조회](/ko/v1.4/api/batch/jobs) 응답의 `error`(`code` / `message` / `details`)로 제공됩니다.

**BLOCK은 오류가 아닙니다** — 검사를 완수한 정상 판정이므로 `COMPLETED` + `action: "BLOCK"`으로 반환됩니다. [배치 개요](/ko/v1.4/api/batch/overview)를 참고하세요.

## 요청 · 접수 시점 (HTTP 응답)

오류 봉투는 인라인 [Guard API의 오류 형식](/ko/v1.4/api/errors)과 동일합니다:

```json theme={"dark"}
{
  "ok": false,
  "error": {
    "code": "S3_TARGET_NOT_ALLOWED",
    "message": "tgt_s3_url is outside the allowed write scope",
    "details": "connection 's3-prod' allows WRITE on s3://your-bucket/deidentified/*"
  }
}
```

| HTTP | `error.code`                   | 상황                                                                               |
| ---- | ------------------------------ | -------------------------------------------------------------------------------- |
| 401  | `UNAUTHORIZED`                 | API Key 미제공 또는 무효                                                                |
| 403  | (활성 상태 관련 코드)                  | 비활성화 또는 [Kill Switch](/ko/v1.4/admin/kill-switch) 발동 중 — 발동 중에는 생성 · 조회 모두 거부됩니다 |
| 400  | `BAD_REQUEST`                  | 요청 형식 오류 — URL 형식 위반, 지원하지 않는 `process_type` 등                                   |
| 400  | `S3_CONNECTION_NOT_CONFIGURED` | 프로젝트에 [Storage Connection](/ko/v1.4/api/batch/storage-connection) 미등록            |
| 400  | `S3_TARGET_NOT_ALLOWED`        | `src` / `tgt`가 허용 범위(버킷 · 경로 · 읽기/쓰기 모드) 밖                                       |
| 404  | `NOT_FOUND`                    | 존재하지 않는 작업 ID 조회                                                                 |
| 502  | `BAD_GATEWAY`                  | Starfort 내부 일시 장애 — 재시도하세요                                                       |

## 처리 시점 실패 (작업 `error.code`)

작업 조회 응답의 `status: "FAILED"`와 함께 `error.code`로 반환됩니다. 실패한 작업은 `tgt`에 아무것도 저장하지 않습니다.

| `error.code`                                 | 상황                                                            |
| -------------------------------------------- | ------------------------------------------------------------- |
| `SRC_FETCH_FAILED`                           | 원본을 읽지 못함 — 객체 미존재, 접근 권한 거부 등                                |
| `SRC_UNSUPPORTED_TYPE`                       | 미지원 형식 또는 확장자 · 내용 불일치(위장 파일)                                 |
| `FILE_TOO_LARGE` / `TEXT_TOO_LONG`           | 파일 크기 · 텍스트 길이 [한도](/ko/v1.4/api/batch/outputs-and-limits) 초과 |
| `GUARDIAN_CALL_FAILED` / `GUARDIAN_REJECTED` | 분석 엔진 처리 실패 — `details`에 상세 사유                                |
| `TGT_WRITE_FAILED`                           | 결과 저장 실패 — 쓰기 권한 · 용량 등                                       |
| `KILL_SWITCH_ACTIVATED`                      | 접수 후 Kill Switch 발동 — 대기 · 진행 중 작업이 산출물 없이 실패 확정              |
| `JOB_EXPIRED`                                | 재시도 한도 내 처리 미완 — 재접수하세요                                       |

## 권장 처리 방식

<Steps>
  <Step title="작업 생성의 HTTP 상태 확인">202 = 접수됨(`job_id` 보관); 4xx/5xx = 작업 미생성 — `error.code`로 분기해 요청을 교정하거나 재시도하세요.</Step>
  <Step title="조회에서 `status`로 분기">`COMPLETED` = 판정(`action`) 확인; `FAILED` = `error.code`로 분기.</Step>
  <Step title="실패 처리">`SRC_*` / `S3_*` 계열은 버킷 · 권한 · 파일을 교정한 뒤 재접수하고, `GUARDIAN_*` / `JOB_EXPIRED` / 502는 백오프를 적용해 재시도(재접수)하세요.</Step>
</Steps>