---
url: https://docs.snapotter.com/ko/api/errors.md
description: 오류 본문의 형식, 안정적인 코드, 그리고 각 코드에 대한 대응 방법입니다.
---

# 오류 코드

모든 JSON 오류 응답은 같은 형식을 가집니다.

```json
{
  "error": "Job not found",
  "code": "NOT_FOUND",
  "requestId": "req-42"
}
```

| 필드 | 항상 포함 | 의미 |
|-------|----------------|---------|
| `error` | 예 | 사람이 읽을 수 있는 메시지입니다. 사용자에게 그대로 보여 줘도 안전합니다. 파싱하지 마세요. |
| `code` | 예 | 안정적이고 기계가 읽을 수 있는 코드입니다. 이 값으로 분기하세요. |
| `requestId` | 예 | 이 요청에 대한 서버의 ID입니다. 문제를 보고할 때 함께 알려 주세요. 서버 로그와 일치합니다. |
| `details` | 경우에 따라 | 검증 메시지처럼 일부 4xx 오류에 대한 추가 정보입니다. |

메시지는 릴리스마다 바뀔 수 있습니다. 코드는 바뀌지 않으므로 클라이언트 로직은 `code` 기준으로 작성하세요.

## HTTP 상태에서 파생되는 코드

라우트가 자체 코드를 지정하지 않으면 서버는 상태에서 코드를 만들어 냅니다.

| HTTP 상태 | `code` |
|-------------|--------|
| 400 | `BAD_REQUEST` |
| 401 | `AUTH_REQUIRED` |
| 403 | `FORBIDDEN` |
| 404 | `NOT_FOUND` |
| 409 | `CONFLICT` |
| 413 | `PAYLOAD_TOO_LARGE` |
| 415 | `UNSUPPORTED_MEDIA_TYPE` |
| 422 | `UNPROCESSABLE_ENTITY` |
| 429 | `RATE_LIMITED` |
| 500 | `INTERNAL_ERROR` |
| 501 | `NOT_IMPLEMENTED` |
| 503 | `SERVICE_UNAVAILABLE` |
| 507 | `INSUFFICIENT_STORAGE` |

그 외의 4xx는 `BAD_REQUEST`로, 그 외의 5xx는 `INTERNAL_ERROR`로 처리됩니다.

라우트가 더 구체적인 코드를 지정할 수 있으며, 이 경우 응답에는 해당 코드가 대신 포함됩니다. 예를 들어 AI 번들이 없어 실행할 수 없는 도구는 기능별 코드를 반환합니다. 이러한 코드는 해당 코드를 발생시키는 기능과 함께 설명합니다.

## 인증과 접근

| `code` | 상태 | 대응 방법 |
|--------|--------|------------|
| `AUTH_REQUIRED` | 401 | 세션 토큰 또는 API 키(`si_...`)와 함께 `Authorization: Bearer <token>`를 보내세요. |
| `FORBIDDEN` | 403 | 자격 증명은 유효하지만 권한이 없습니다. 관리자에게 권한을 요청하세요. |
| `MUST_CHANGE_PASSWORD` | 403 | 다른 엔드포인트를 호출하려면 먼저 계정의 비밀번호를 변경해야 합니다. 세션 토큰으로 `POST /api/auth/change-password`를 호출한 뒤 다시 시도하세요. |
| `USER_DISABLED` | 403 | 계정이 비활성화되어 있습니다. 관리자가 다시 활성화해야 합니다. |
| `LOGIN_THROTTLED` | 429 | 로그인 실패 횟수가 너무 많습니다. 잠시 기다린 후 다시 시도하세요. |
| `VALIDATION_ERROR` | 400 | 요청 본문 또는 매개변수가 검증에 실패했습니다. `details`에 문제가 표시됩니다. |

처음 실행할 때의 관리자 계정은 `admin`이고 비밀번호는 `admin`이며, `DEFAULT_USERNAME` 또는 `DEFAULT_PASSWORD`가 이를 변경한 경우는 예외입니다. `SKIP_MUST_CHANGE_PASSWORD`가 설정되어 있지 않으면, 비밀번호를 변경할 때까지 이 계정은 모든 호출에서 `MUST_CHANGE_PASSWORD`를 받습니다.

## 작업

실패한 작업은 HTTP 오류가 아니라 작업 자체에 실패 이유를 보고합니다. `GET /api/v1/jobs/{jobId}`에서 `error.code`와 `error.message`를 읽으세요. [진행 상황 추적](/ko/api/rest#progress-tracking)을 참고하세요.

실패한 작업은 실패 원인이 입력 오류이거나 서버 결함일 때만 `error.code`를 유지합니다. 그 외의 실패에는 메시지만 포함됩니다.

| `code` | 의미 | 대응 방법 |
|--------|---------|------------|
| `CANCELED` | 사용자가 작업을 취소했습니다. HTTP 상태가 아닙니다. 진행 이벤트는 이 코드와 함께 `phase: failed`를 전달합니다. | 사용자 취소로 처리하세요. 자동으로 다시 시도하지 마세요. |
| `INPUT_MISSING` | 작업이 실행되기 전에 입력이 제거되었습니다. | 파일을 다시 업로드하세요. |
| `ENGINE_UNAVAILABLE` | 필요한 엔진을 서버에서 시작하지 못했습니다. | 관리자가 설치를 복구한 후 다시 시도하세요. |
| `JOB_STALLED` | 클라이언트에는 반환되지 않으며, 서버의 오류 보고서에 붙는 레이블입니다. 워커가 큐에서 허용하는 횟수보다 많이 작업의 잠금을 잃었으며, 대개 서버가 재시작되었거나 메모리 또는 CPU가 부족했기 때문입니다. 작업은 중단되었다는 메시지와 함께 실패합니다. | 다시 시도하세요. 계속 발생하면 서버에 메모리를 더 할당하거나 `CONCURRENT_JOBS`를 낮추세요. |

## 인증과 MFA

| `code` | 상태 | 의미 | 대응 방법 |
|--------|--------|---------|------------|
| `MFA_ENROLLMENT_REQUIRED` | 403 | MFA 정책이 등록을 요구하지만, 이 인스턴스는 사용자를 등록할 수 없습니다(엔터프라이즈 라이선스 없음). 라이선스가 있는 인스턴스는 200과 `requiresMfaEnrollment: true`를 반환하고 대신 사용자가 등록을 진행하도록 안내합니다. | 다시 시도하지 마세요. 관리자가 정책을 변경하거나 오프라인 복구 CLI를 사용해야 합니다. |
| `MFA_POLICY_UNAVAILABLE` | 503 | 로그인 중 서버가 MFA 정책을 읽지 못했습니다. | 잠시 후 로그인을 다시 시도하세요. |
| `INVALID_CODE` | 401 | TOTP 또는 복구 코드가 올바르지 않습니다. | 사용자에게 새 코드를 요청한 후 다시 시도하세요. 실패가 반복되면 `MFA_ATTEMPTS_EXHAUSTED`로 끝납니다. |
| `MFA_ATTEMPTS_EXHAUSTED` | 401 | 잘못된 코드가 너무 많습니다. 챌린지가 폐기됩니다. | 로그인을 처음부터 다시 시작해 새 챌린지를 받으세요. |
| `MFA_EXPIRED` | 401 | MFA 또는 등록 챌린지가 만료되었거나 일치하지 않습니다. | 로그인을 다시 시작하세요. |
| `MFA_NOT_CONFIGURED` | 401 | 계정에 TOTP 비밀 키가 없어 코드를 확인할 수 없습니다. | 코드로 로그인하기 전에 MFA를 등록하세요. |
| `MFA_ALREADY_ENABLED` | 409 | 계정에서 MFA가 이미 활성화되어 있습니다. | 다시 등록하지 마세요. |
| `NO_PENDING_ENROLLMENT` | 400 | 대기 중인 등록이 없는데 등록 확인 요청이 도착했습니다. | 먼저 등록 엔드포인트를 호출하세요. |
| `MFA_NOT_ENABLED` | 400 | 이 작업은 MFA가 켜져 있어야 하는데, 이 사용자는 꺼져 있습니다. | 작업을 건너뛰거나 먼저 MFA를 활성화하세요. |
| `MFA_DECRYPTION_FAILED` | 500 | 저장된 TOTP 비밀 키를 복호화할 수 없습니다. | 운영자 조치가 필요합니다. 대개 암호화 키가 변경되었다는 뜻입니다. `DATA_ENCRYPTION_KEY`와 `DATA_ENCRYPTION_KEY_PREVIOUS`를 확인하세요. |
| `DECRYPTION_FAILED` | 500 | 저장된 값(설정, 웹훅 인증 헤더 또는 TOTP 비밀 키)을 복호화할 수 없습니다. | 위와 같이 운영자 조치가 필요합니다. 다시 시도하지 마세요. |
| `IDLE_TIMEOUT` | 401 | 일정 시간 동안 활동이 없어 세션이 만료되었습니다. | 다시 로그인하세요. |
| `INVALID_PASSWORD` | 401 | 비밀번호 변경 시 현재 비밀번호가 올바르지 않습니다. | 사용자에게 현재 비밀번호를 요청하세요. |
| `PASSWORD_CHANGED` | 409 | 이 요청이 실행되는 동안 다른 세션에서 비밀번호가 변경되었거나 관리자가 비밀번호를 재설정했습니다. | 다시 로그인하세요. |
| `OIDC_NO_PASSWORD` | 400 | SSO로 생성된 계정에 대해 비밀번호 변경 또는 재설정이 요청되었습니다. | 사용자를 ID 공급자로 안내하세요. |

## OIDC

로그인 중 OIDC 실패는 JSON 본문을 반환하지 않습니다. 로그인 라우트는 일반적인 이유와 함께 로그인 페이지로 리디렉션하며, 감사 로그에 코드가 기록됩니다. 로그아웃 라우트는 ID 공급자에 연결할 수 없을 때에도 로컬 세션을 종료합니다.

| `code` | 상태 | 의미 | 대응 방법 |
|--------|--------|---------|------------|
| `OIDC_ISSUER_SCHEME_MISMATCH` | 없음(리디렉션) | 발급자 URL이 `http`이지만 `EXTERNAL_URL`가 `https`이므로 클라이언트가 디스커버리를 거부합니다. | 관리자: 발급자를 `https`로 제공하거나, 인스턴스를 `http`로 실행하세요. |
| `OIDC_DISCOVERY_TIMEOUT` | 없음(리디렉션) | 발급자 디스커버리가 시간 초과되었습니다. | 서버가 발급자에 접근할 수 있는지 확인한 후 다시 시도하세요. |
| `OIDC_DISCOVERY_FAILED` | 없음(리디렉션) | 다른 이유로 디스커버리에 실패했습니다. | 발급자 URL과 서버의 아웃바운드 접근을 확인하세요. |
| `OIDC_END_SESSION_INVALID` | 없음(로그아웃 계속 진행) | ID 공급자의 `end_session_endpoint`가 올바른 URL이 아닙니다. 로컬 세션은 그대로 삭제됩니다. | 관리자: 공급자의 메타데이터를 수정하세요. |
| `OIDC_END_SESSION_SCHEME` | 없음(로그아웃 계속 진행) | `end_session_endpoint`가 서버에서 허용하지 않는 스킴을 사용합니다. 로컬 세션은 그대로 삭제됩니다. | 관리자: 공급자의 메타데이터를 수정하세요. |

## SAML

SAML 실패는 `code`를 설정하지 않습니다. 실패한 어설션은 `saml_auth_failed`와 함께 로그인 페이지로 리디렉션되며, `SAML_LOGIN_FAILED` 감사 이벤트에 이유가 기록됩니다.

## SCIM

SCIM 라우트는 RFC 7644 오류 봉투(`schemas`, `detail`, `status`, 그리고 경우에 따라 `scimType`)로 응답합니다. `code`를 설정하지 않습니다. HTTP 상태로 분기하세요.

## 팀, 역할, 사용자

팀 또는 역할 이름이 중복되면 일반 `CONFLICT`를 반환하고, 팀 또는 역할이 없으면 `NOT_FOUND`를 반환합니다.

| `code` | 상태 | 의미 | 대응 방법 |
|--------|--------|---------|------------|
| `ESCALATION_DENIED` | 403 | 호출자의 역할로는 이 변경을 할 수 없습니다. 대상이 호출자의 권한보다 위에 있거나, 역할이 기본 제공 역할이거나, 요청이 호출자가 가지지 않은 권한을 부여합니다. | 다시 시도하지 마세요. 더 높은 권한을 가진 사용자에게 요청하세요. |
| `UNKNOWN_ROLE` | 400 | 역할 ID가 기존 역할과 일치하지 않습니다. | 역할 ID를 수정하세요. 역할 목록을 조회해 찾을 수 있습니다. |
| `UNKNOWN_TEAM` | 400 | 팀 ID가 기존 팀과 일치하지 않습니다. | 팀 ID를 수정하세요. |
| `SELF_DEMOTE` | 400 | 관리자가 자신의 관리자 역할을 제거하려고 했습니다. | 다른 관리자가 변경하도록 하세요. |
| `SELF_DELETE` | 400 | 관리자가 자신의 계정을 삭제하려고 했습니다. | 다른 관리자가 삭제하도록 하세요. |
| `LAST_ADMIN` | 사용자 라우트에서는 400, GDPR 삭제 라우트에서는 409 | 이 변경으로 관리자가 한 명도 남지 않거나, 모든 관리자가 속한 팀이 삭제됩니다. | 먼저 다른 사용자를 관리자로 지정하세요. |
| `USER_LIMIT_REACHED` | 403 | 인스턴스가 `MAX_USERS` 한도에 도달했습니다. | 사용자를 제거하거나 `MAX_USERS`를 늘리세요. |

## 기능과 AI 번들

선택 사항인 AI 번들이 필요한 도구, 배치 실행, 파이프라인은 이 코드를 사용합니다.

| `code` | 상태 | 의미 | 대응 방법 |
|--------|--------|---------|------------|
| `FEATURE_NOT_INSTALLED` | 501, 또는 스마트 크롭의 얼굴 모드에서는 400 | 도구, 또는 파이프라인이나 배치의 한 단계에 설치되지 않은 번들이 필요합니다. 본문에는 `feature`(번들 ID)와 `featureName`가 포함됩니다. | 설정에서 번들을 설치한 후 다시 시도하세요. |
| `FEATURE_CPU_UNSUPPORTED` | 409 | 번들의 x86-64 라이브러리에 AVX가 필요한데 이 서버의 CPU에는 AVX가 없어 설치 또는 오프라인 가져오기가 거부되었습니다. 다운로드되거나 설치된 것은 없습니다. 본문에는 `feature`(번들 ID)와 `reason`(`cpu-no-avx`)이 포함됩니다. `GET /api/v1/features`는 같은 번들을 `compatibility: "incompatible"` 및 `compatibilityReason: "cpu-no-avx"`와 함께 보고합니다. | AVX가 있는 CPU 또는 arm64에서 SnapOtter를 실행하세요. 다른 번들은 계속 설치할 수 있습니다. |
| `FEATURE_INCOMPATIBLE` | 501, 또는 빠른 OCR이 읽을 수 없는 언어를 받으면 400 | 설치된 기능이 요청한 품질이나 언어를 처리할 수 없습니다. | 설정을 변경하거나 해당 설정을 지원하는 번들을 설치하세요. |
| `ENGINE_UNAVAILABLE` | 503 | 필요한 엔진을 시작하지 못했거나, 요청이 검증된 후 OCR 런타임이 제거되었습니다. | 관리자가 기능을 복구하거나 다시 설치한 후 다시 시도하세요. |
| `BROWSER_NOT_AVAILABLE` | 503 | Chromium이 설치되어 있지 않아 HTML을 이미지로 변환할 수 없습니다. | 관리자에게 브라우저 설치를 요청하세요. |
| `BROWSER_CRASHED` | 503 | 렌더링 중 스크린샷 브라우저가 충돌했습니다. | 요청을 다시 시도하세요. |

## 도구

| `code` | 상태 | 의미 | 대응 방법 |
|--------|--------|---------|------------|
| `INPUT_MISSING` | 410 | 업로드한 입력이 작업이 실행되기 전에 제거되었습니다. | 파일을 다시 업로드한 후 작업을 제출하세요. |
| `ANALYSIS_EXPIRED` | 410 | 여권 사진 분석이 생성 전에 만료되었습니다. | 사진을 다시 분석한 후 생성하세요. |
| `BACKGROUND_REMOVAL_EXPIRED` | 410 | 배경 제거 결과가 후속 단계 전에 만료되었습니다. | 배경을 다시 제거하세요. |
| `NOT_ANIMATED` | 400 | GIF 배경 제거에 정지 이미지가 전달되었습니다. | 정지 이미지에는 배경 제거를 사용하세요. |
| `TOO_MANY_FRAMES` | 400 | 애니메이션의 프레임 수가 서버에서 허용하는 수(`GIF_BG_MAX_FRAMES`)를 초과합니다. | 더 짧은 애니메이션을 보내거나 관리자에게 한도를 늘려 달라고 요청하세요. |
| `TOO_MANY_PIXELS` | 400 | 애니메이션의 캔버스 크기에 프레임 수를 곱한 값이 서버 한도를 초과합니다. GIF 배경 제거는 268,402,689픽셀(16383 x 16383)이고, 다른 애니메이션 도구는 GIF 작업량 상한입니다. | 프레임 수를 줄이거나 더 작은 애니메이션을 보내세요. |
| `IMAGE_TOO_LARGE` | 400 | 이미지의 픽셀 수가 디코더가 허용하는 수를 초과합니다. | 더 작은 이미지를 보내세요. |
| `RESULT_TOO_LARGE` | 400 | 이 설정으로는 인코더 또는 픽셀 한도가 허용하는 것보다 큰 이미지가 만들어집니다. | 더 작은 이미지를 사용하거나 결과가 더 작아지는 설정을 사용하세요. |
| `DOCUMENT_UNREADABLE` | 400 | LibreOffice 또는 pandoc이 문서를 열 수 없었습니다. 문서가 손상되었거나, 암호로 보호되어 있거나, 확장자와 다른 형식일 수 있습니다. | 오피스 앱에서 파일이 열리는지 확인한 후 다시 보내세요. |
| `PDF_DAMAGED` | 400 | PDF 엔진이 손상된 문서 구조를 발견했습니다. | 파일을 PDF 복구로 처리한 후 다시 시도하세요. |
| `PDF_PASSWORD_PROTECTED` | 400 | PDF가 암호화되어 있어 이 도구로 열 수 없습니다. | 먼저 PDF 잠금 해제로 잠금을 해제하세요. |
| `NO_AUDIO_TRACK` | 400 | 오디오 도구가 사용할 오디오 스트림이 파일에 없습니다. | 오디오가 있는 파일을 보내세요. |
| `MEDIA_UNDECODABLE` | 400 | ffmpeg가 오디오 또는 비디오를 읽을 수 없었습니다. 패킷, 코덱 매개변수, `moov` 아톰을 찾지 못했거나 파싱할 수 없는 데이터가 있습니다. | 미디어 플레이어에서 파일이 재생되는지 확인하거나 다시 내보낸 후 다시 시도하세요. |
| `PAGE_OUT_OF_RANGE` | 400 | 페이지 범위가 PDF에 없는 페이지를 지정합니다. | 페이지 수를 확인하고 그 안의 범위를 보내세요. |
| `INVALID_PAGE_RANGE` | 400 | 페이지 범위의 구문이 올바르지 않습니다. | `1-3,5`와 같은 페이지 번호를 사용하세요. |
| `CANNOT_REMOVE_ALL_PAGES` | 400 | 페이지 제거에서 모든 페이지를 제거하라는 요청을 받았습니다. | 최소 한 페이지는 남겨 두세요. |
| `NESTING_TOO_DEEP` | 400 | JSON 또는 XML의 중첩이 100단계를 초과합니다. | 문서를 평탄화한 후 변환하세요. |
| `IMAGE_UNDECODABLE` | 400 | 이미지를 디코딩할 수 없거나 크기를 읽을 수 없습니다. 파일이 손상되었거나 디코더가 지원하지 않는 인코딩을 사용할 수 있습니다. | 다른 앱에서 이미지를 다시 내보내거나 먼저 PNG 또는 JPEG로 변환하세요. |
| `INVALID_SETTINGS` | 400 | 설정이 범위를 벗어났거나 이 파일에 맞지 않습니다. 이미지 밖의 자르기, 0으로 설정한 크기 조정, 애니메이션에 없는 GIF 프레임, 존재하지 않는 여권 규격 등이 해당합니다. `error` 텍스트에 해당 설정이 표시됩니다. | `error`에 표시된 설정을 수정한 후 다시 시도하세요. |
| `CHART_DATA_INVALID` | 400 | 차트 메이커가 파일에서 차트 데이터를 읽을 수 없었습니다. CSV 또는 JSON을 파싱할 수 없거나, 숫자 열이 없거나, 행이 100개를 초과하거나, 음수 값이 있습니다. `error` 텍스트에 어느 경우인지 표시됩니다. | 최대 100행의 CSV 또는 JSON을 보내세요. 각 행은 레이블과 0 이상의 숫자로 구성합니다. |
| `NO_FACE_DETECTED` | 400 | 여권 사진에서 이미지의 얼굴을 찾지 못했습니다. | 조명이 좋고 정면을 향한 선명한 사진을 보내세요. |
| `TARGET_SIZE_UNREACHABLE` | 400 | 압축 또는 여권 사진의 크기 제한이 크기를 줄여도 파일을 요청한 크기 이하로 만들 수 없습니다. | 목표 크기를 더 크게 지정하거나 먼저 이미지를 자르세요. |
| `TOO_MANY_PAGES` | 400 | OCR이 한 작업에서 처리하는 것보다 많은 페이지를 요청받았습니다. | 페이지 범위로 더 적은 페이지를 선택하세요. |
| `METADATA_DAMAGED` | 400 | 메타데이터 편집에서 이미지의 기존 EXIF 데이터가 손상된 것을 발견해 안전하게 다시 쓸 수 없습니다. | 먼저 이미지 메타데이터 제거로 메타데이터를 제거한 후 편집하세요. |
| `REMOTE_RESOURCES_DISABLED` | 400 | HTML 또는 Markdown을 PDF로 변환하는 중 네트워크에 있는 이미지, 스타일시트 또는 글꼴에 대한 참조를 발견했으며, 서버는 이를 가져오지 않습니다. | 리소스를 파일에 포함한(예: `data:` URI로) 후 다시 시도하세요. |

## 파일

| `code` | 상태 | 의미 | 대응 방법 |
|--------|--------|---------|------------|
| `STORAGE_QUOTA_EXCEEDED` | 413 | 파일에 저장하면 사용자의 저장 용량 할당량을 초과합니다. | 파일을 삭제하거나 관리자에게 더 많은 공간을 요청하세요. |
| `INVALID_STORED_NAME` | 400 | 서버가 저장된 파일 이름을 거부했습니다. | 파일을 다시 업로드하세요. |

## 파이프라인과 배치

파이프라인과 배치 요청은 번들이 필요한 각 단계에 대해 위의 기능 코드를 반환합니다. 이미 사용 중인 작업 ID는 상태 409와 함께 `CONFLICT`를 반환합니다. 새 작업 ID를 보내세요.

## 설정

| `code` | 상태 | 의미 | 대응 방법 |
|--------|--------|---------|------------|
| `UNKNOWN_SETTING` | 400 | 이 키는 알려진 설정이 아닙니다. | 키 이름을 확인하세요. |
| `READONLY_SETTING` | 400 | 이 설정은 API로 변경할 수 없습니다. | 환경 변수 또는 관리자 UI에서 변경하세요. |
| `DEPENDENCY_VALIDATION_FAILED` | 400 | 새 값이 다른 설정과 충돌합니다. 본문은 `setting`에 설정을 표시하고 `validationErrors`에 문제를 나열합니다. | 나열된 설정을 수정한 후 다시 시도하세요. |
| `SETTING_DECRYPTION_FAILED` | 500 | 저장된 설정을 복호화할 수 없습니다. | `DECRYPTION_FAILED`와 같이 운영자 조치가 필요합니다. |

설정에서 `VALIDATION_ERROR`인 경우 `details`에 스키마 문제가 담깁니다.

## 엔터프라이즈

| `code` | 상태 | 의미 | 대응 방법 |
|--------|--------|---------|------------|
| `FEATURE_NOT_LICENSED` | 403 | 설정 또는 정책에 엔터프라이즈 라이선스가 필요합니다(예: SSO 강제 적용 또는 MFA 정책). | 라이선스가 있는 인스턴스를 사용하거나 해당 설정을 끈 상태로 두세요. |
| `IP_NOT_ALLOWED` | 403 | 요청의 IP 주소가 허용 목록에 없습니다. | 허용된 네트워크에서 접속하세요. |
| `INVALID_CIDR` | 400 | 허용 목록 항목이 올바른 CIDR이 아닙니다. 메시지에 잘못된 항목이 나열됩니다. | 항목을 수정한 후 다시 저장하세요. |
| `SELF_LOCKOUT` | 400 | 허용 목록을 저장하면 호출자의 현재 IP가 차단됩니다. | 먼저 현재 IP를 목록에 추가하세요. |

GDPR 삭제 라우트는 사용자 또는 팀이 법적 보존 상태일 때 상태 409와 함께 일반 `CONFLICT`를 반환합니다.

## 클라이언트가 받지 않는 코드

이 코드는 로그, 텔레메트리 또는 Fastify 자체 오류를 위해 서버 소스에 존재합니다. 클라이언트는 응답 본문이나 작업 행에서 이 코드를 받지 않으므로 이 코드를 기준으로 클라이언트 로직을 작성하지 마세요.

| `code` | 전달 위치 |
|--------|---------------|
| `ALERT_DECRYPTION_FAILED` | 알림 평가기가 오류 추적에 보고합니다. 알림 웹훅의 인증 헤더를 복호화할 수 없습니다. |
| `SIEM_DECRYPTION_FAILED` | SIEM 전달이 오류 추적에 보고합니다. SIEM 인증 헤더를 복호화할 수 없습니다. |
| `WEBHOOK_DECRYPTION_FAILED` | 오류 추적에 보고됩니다. 같은 실패를 겪은 요청은 `DECRYPTION_FAILED`로 응답합니다. |
| `STAGED_DISCARD_FAILED` | 스테이징된 업로드를 제거할 수 없을 때 오류 추적에 보고됩니다. |
| `USERNAME_RACE_EXHAUSTED` | SSO 자동 생성이 모든 재시도에서 사용자 이름 경합에 실패할 때 발생합니다. 대신 로그인 페이지에 오류가 표시됩니다. |
| `ERR_OUT_OF_RANGE` | 오브젝트 스토리지 리더가 잘못된 바이트 범위에 대해 발생시킵니다. |
| `ETIMEDOUT` | GDPR 내보내기의 시간 초과 오류에 설정됩니다. 내보내기는 실패하며 다시 요청할 수 있습니다. |
| `FST_REQ_FILE_TOO_LARGE` | 제한을 초과한 업로드에 대한 Fastify의 코드입니다. 클라이언트는 `PAYLOAD_TOO_LARGE`와 함께 413을 받거나, 라우트 자체의 413 메시지를 받습니다. |
| `TARGET_SIZE_EXCEEDED` | 목표 크기 압축이 목표를 달성하지 못했을 때 발생합니다. 오류에 상태나 코드가 없으므로 클라이언트는 일반적인 실패를 받습니다. |
| `OCR_CACHE_PERMISSIONS` | AI 데이터 볼륨 때문에 OCR 런타임 캐시가 모든 사용자에게 쓰기 가능한 상태가 되면 운영상 결함으로 오류 추적에 보고됩니다. 설치 작업은 스토리지 문제를 명시한 메시지와 함께 실패합니다. |
| `OCR_RUNTIME_UNREACHABLE` | 서버가 OCR 런타임을 내려받기 위해 huggingface.co에 접속하지 못하면 운영상 결함으로 오류 추적에 보고됩니다. 설치 작업은 네트워크 접근, `HTTPS_PROXY`, 오프라인 가져오기에 대한 메시지와 함께 실패합니다. |
