배치 오류 - Starfort

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

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

BLOCK은 오류가 아닙니다 — 검사를 완수한 정상 판정이므로 COMPLETED + action: "BLOCK"으로 반환됩니다. 배치 개요를 참고하세요.

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

오류 봉투는 인라인 Guard API의 오류 형식과 동일합니다:

{
  "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 발동 중 — 발동 중에는 생성 · 조회 모두 거부됩니다
400	`BAD_REQUEST`	요청 형식 오류 — URL 형식 위반, 지원하지 않는 `process_type` 등
400	`S3_CONNECTION_NOT_CONFIGURED`	프로젝트에 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`	파일 크기 · 텍스트 길이 한도 초과
`GUARDIAN_CALL_FAILED` / `GUARDIAN_REJECTED`	분석 엔진 처리 실패 — `details`에 상세 사유
`TGT_WRITE_FAILED`	결과 저장 실패 — 쓰기 권한 · 용량 등
`KILL_SWITCH_ACTIVATED`	접수 후 Kill Switch 발동 — 대기 · 진행 중 작업이 산출물 없이 실패 확정
`JOB_EXPIRED`	재시도 한도 내 처리 미완 — 재접수하세요

권장 처리 방식

작업 생성의 HTTP 상태 확인

202 = 접수됨(job_id 보관); 4xx/5xx = 작업 미생성 — error.code로 분기해 요청을 교정하거나 재시도하세요.

조회에서 `status`로 분기

COMPLETED = 판정(action) 확인; FAILED = error.code로 분기.

실패 처리

SRC_* / S3_* 계열은 버킷 · 권한 · 파일을 교정한 뒤 재접수하고, GUARDIAN_* / JOB_EXPIRED / 502는 백오프를 적용해 재시도(재접수)하세요.

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

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

​권장 처리 방식

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

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

권장 처리 방식