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

# 주소 증명 경고 및 오류 코드

> 성명 불일치, 만료된 문서, 메타데이터 문제 등 Didit 주소 증명의 모든 경고 코드를 안내합니다. 경고별 자동 거부 규칙을 설정할 수 있습니다.

## 개요

주소 증명(POA) 인증은 추출 및 포렌식 분석 중에 감지된 모든 품질, 진위 여부 또는 일치 문제에 대해 `poa_verifications[].warnings[]`에 경고를 생성합니다. 각 경고는 `feature`가 `"PROOF_OF_ADDRESS"`로 설정된 [경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체)입니다. 몇 가지 위험은 항상 강제로 `Declined` 처리를 유발하며, 나머지는 워크플로에 설정된 위험별 작업(`DECLINE` / `REVIEW` / `NO_ACTION`)을 따릅니다.

아래의 모든 위험은 실제 프로덕션 의사 결정 파이프라인과 대조하여 검증되었습니다. 표에는 정확한 짧은 설명 및 긴 설명 문자열이 그대로 재현되어 있습니다.

> [!NOTE]
>
> POA 추출에는 문서당 **5–15초**의 지연 시간이 발생합니다. 경고는 워크플로 단계가 완료될 때만 기록되므로, 5초보다 빠른 주기로 폴링하지 마십시오.

## 두 가지 프로덕션 경로

POA 경고는 두 가지 서로 다른 경로에서 생성되며, 경로에 따라 위험 세트가 다릅니다:

* **워크플로 세션**(인증 세션 내부의 POA 단계) — 업로드 endpoint는 먼저 재시도 루프(참조: [재시도 동작](#재시도-동작-워크플로-세션))와 함께 차단 유효성 검사를 실행한 다음, `check_poa_risks`와 다중 문서 이름 확인을 통해 최종 저장될 경고를 계산합니다.
* **독립형 API**(`POST /v3/poa/`) — 경고는 `check_poa_risks`에서만 생성됩니다. 재시도 루프가 없고, 인증된 신분증 컨텍스트가 없으며, 문서가 하나뿐이므로 `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`, `POA_MAX_ATTEMPTS_EXCEEDED`, `FUTURE_ISSUE_DATE`는 독립형 API에서 **절대** 생성되지 않습니다. 이 경로에서는 추출 전 유효성 검사 오류가 무시됩니다.

`POOR_DOCUMENT_QUALITY`는 위험 enum에 정의되어 있고 작업 매핑에 예약되어 있지만, **POA 파이프라인의 어떤 코드 경로도 이를 생성하지 않습니다**. 즉, 두 경로 모두에서 `warnings[]`에 절대 나타나지 않습니다. 이를 기준으로 분기 처리를 하지 마십시오.

## 자동 거부 경고 (항상 강제로 `Declined`)

이 위험들은 `AUTO_DECLINE_RISKS`에 속해 있습니다. 기록되면 설정과 관계없이 POA 상태는 `Declined`가 되며, `log_type`은 항상 `error`입니다.

| 위험 | 원인 | 권장 해결 방법 |
| - | - | - |
| `MISSING_ADDRESS_INFORMATION` | 문서에서 주소를 추출할 수 없습니다. | 주소가 명확하게 표시된 문서를 다시 제출하도록 사용자에게 요청하십시오. |
| `POA_DOCUMENT_EXPIRED` | 문서는 두 가지 경로 중 하나로 인해 만료되었습니다: **인쇄된 만료일**이 지났거나, 해당 유형에 대해 **설정된 최대 유효 기간보다 오래되었습니다**. 기본값: `UTILITY_BILL` 및 `BANK_STATEMENT`의 경우 **3개월**, `GOVERNMENT_ISSUED_DOCUMENT` 및 `OTHER_POA_DOCUMENT`의 경우 **12개월**(1개월은 30일로 계산되며, `-1`은 검사를 비활성화함). `additional_data`에는 항상 `expiration_reason`(`printed_expiration` 또는 `age_window`), `document_type`, `document_subtype`, `issue_date`가 포함됩니다. `printed_expiration` 경로에서는 `expiration_date`가 추가되고, `age_window` 경로에서는 `max_age_months`가 추가됩니다. | 사용자에게 유효하거나 더 최근의 문서를 요청하거나, 해당 유형의 `age_months`를 늘리십시오. |
| `INVALID_DOCUMENT_TYPE` | 문서를 지원되는 어떤 POA 유형으로도 분류할 수 없습니다(`document_type`이 `UNKNOWN`으로 대체됨). | 사용자에게 다시 제출하도록 요청하십시오. 파일이 손상되지 않았는지 확인하십시오. |
| `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | 문서 유효 기간 검사 자체가 실패했습니다(발급일로부터 만료를 계산하는 중 오류 발생). | 발급일이 명확하게 읽히는 문서를 사용자에게 요청하십시오. |

`FUTURE_ISSUE_DATE`도 `AUTO_DECLINE_RISKS`에 나열되어 있지만, 추출 전 유효성 검사(발급일이 현재 날짜보다 7일을 초과하여 미래인 경우)에서 단 하나의 생성 경로만 가집니다. 해당 오류는 **워크플로 재시도 루프**에만 전달되어 차단 업로드 오류로 나타나며, 독립형 API에서는 절대 생성되지 않고 `warnings[]`에 기록되지도 않습니다. 참조: [재시도 동작](#재시도-동작-워크플로-세션).

## 구성 가능한 경고

각 경고는 워크플로의 POA 노드에 있는 작업 설정(`DECLINE` / `REVIEW` / `NO_ACTION`) 중 하나를 따릅니다. 경고의 `log_type`은 구성된 작업과 일치합니다. 거부는 `error`, 검토는 `warning`, 조치 없음은 `information`에 해당합니다.

| 위험 | 원인 | 작업 설정 | 기본값 |
| - | - | - | - |
| `NAME_MISMATCH_WITH_PROVIDED` | 문서의 이름이 세션 생성 시 제공된 이름(`expected_details`)과 비교했을 때 `poa_name_match_score_threshold`(기본값 86)보다 낮은 점수를 받습니다. | `poa_name_or_address_mismatch_action` | 검토 |
| `NAME_MISMATCH_ID_VERIFICATION` | 문서의 이름이 확인된 신분증 문서와 비교했을 때 임계값보다 낮은 점수를 받습니다. `additional_data`: `{ poa_name, kyc_name, match_score }`. 워크플로 세션에만 적용됩니다. | `poa_name_or_address_mismatch_action` | 검토 |
| `ADDRESS_MISMATCH_WITH_PROVIDED` | 추출된 주소가 API로 제공된 주소와 다르거나, 두 주소 중 하나를 주거용 주소로 확인할 수 없습니다. | `poa_name_or_address_mismatch_action` | 검토 |
| `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | 문서의 국가가 API로 제공된 국가와 일치하지 않습니다(ISO-3 정규화 기준). `additional_data`: `{ expected_country, extracted_country }`. | `poa_name_or_address_mismatch_action` | 검토 |
| `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | 같은 세션의 POA 문서 두 개 이상에 서로 다른 이름이 있습니다. `additional_data`에는 두 노드 ID, 두 이름, 일치 점수가 포함됩니다. 워크플로 세션에만 적용됩니다. | `poa_name_or_address_mismatch_action` | 검토 |
| `DOCUMENT_METADATA_MISMATCH` | 파일이 비어 있거나(`file_size` 0) EXIF 날짜 형식이 잘못되었습니다. | `poa_document_issues_action` | 검토 |
| `SUSPECTED_DOCUMENT_MANIPULATION` | 포렌식 검사에서 조작 증거가 발견되었습니다. 디지털 서명 후 수정됨(`is_tampered`), 오버레이 텍스트 조작(`additional_data.manipulated_regions` 사각형 포함), 알려진 PDF 편집기 사용, 일관되지 않은 EXIF 날짜, 의심스러운 재내보내기 중 하나에 해당합니다. `additional_data.detection_method`에는 발동된 검사 항목의 이름이 표시됩니다. | `poa_document_authenticity_action` | **거부** |
| `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | 텍스트 필드가 지워진 뒤 다른 글꼴로 다시 입력되었지만, 파일에는 내용이 변경되었는지 여부를 증명할 정보가 없습니다. 온라인 편집기는 변경하지 않은 텍스트도 다시 입력하기 때문입니다. 이 경고는 단독으로 `SUSPECTED_DOCUMENT_MANIPULATION`을 발생시키지 않습니다. 같은 문서에서 다른 신호가 이를 발생시키면 두 작업 중 더 엄격한 작업이 적용됩니다. `additional_data.detection_method`는 `unproven_text_replacement`이며, `replaced_text`와 `manipulated_regions`를 포함합니다. 파일을 끝까지 검사하지 못한 경우에도 이 경고가 발생합니다. 검사되지 않은 부분에 그러한 필드가 있을 수 있기 때문입니다. 이때 `detection_method`는 `analysis_incomplete`이며, 검사된 부분에서 필드가 발견되지 않는 한 `replaced_text`와 `manipulated_regions`는 비어 있습니다. | `poa_document_unproven_text_replacement_action` | 검토 |
| `UNSUPPORTED_DOCUMENT_LANGUAGE` | 문서의 언어가 `poa_languages_allowed`에 없습니다. | `poa_unsupported_language_action` | **거부** |
| `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | 감지된 문서 유형이 문서 국가에 대해 `poa_documents_allowed`에서 활성화되어 있지 않거나, 하위 유형이 명시적으로 비활성화되어 있습니다. | `poa_unsupported_document_type_action` | **거부** |
| `ISSUER_NOT_IDENTIFIED` | 문서에서 발급 기관을 식별할 수 없습니다. | `poa_issuer_not_identified_action` | 검토 |
| `UNABLE_TO_EXTRACT_ISSUE_DATE` | 문서에서 유효한 발급일을 찾을 수 없습니다. | `poa_issue_date_not_detected_action` | 검토 |
| `POA_NAME_NOT_DETECTED` | 문서에서 이름이 감지되지 않았습니다. | `poa_issue_date_not_detected_action` (공유 설정) | 검토 |
| `UNPARSABLE_OR_INVALID_ADDRESS` | 주소가 추출되었지만 파싱되고 지오코딩되어 유효한 주거용 주소로 변환할 수 없습니다. | `poa_unparsable_or_invalid_address_action` | 검토 |
| `POA_MAX_ATTEMPTS_EXCEEDED` | 사용자가 워크플로 재시도 루프에서 `poa_max_retry_attempts`(기본값 2)를 모두 소진했습니다. `additional_data`: `{ attempts }`. 워크플로 세션에만 적용됩니다. | `poa_max_attempts_exceeded_action` | **거부** |

> [!NOTE]
>
> 모든 이름 및 주소 불일치에는 **하나의 공통 작업**이 적용됩니다. `poa_name_or_address_mismatch_action`이 두 이름 위험, 두 주소 위험, 문서 간 이름 검사를 모두 담당하므로 이름 불일치와 주소 불일치의 동작을 따로 구성할 수 없습니다. 독립형 API에서는 같은 그룹이 `poa_address_mismatch_action` 요청 옵션을 따릅니다(`poa_name_mismatch_action` 옵션은 허용되지만 읽히지 않습니다).

## 독립 실행형 API 차이점 (`POST /v3/poa/`)

독립 실행형 endpoint는 동일한 위험-작업 매핑을 구성하지만, `DECLINE` 또는 `NO_ACTION`만 허용하는 요청 수준 옵션을 사용합니다(모두 기본값은 `DECLINE`).

* `UNABLE_TO_EXTRACT_ISSUE_DATE` 및 `POA_NAME_NOT_DETECTED`는 이 endpoint에서 **거부로 하드코딩**되어 있습니다.
* `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` 및 `UNPARSABLE_OR_INVALID_ADDRESS`는 여기서 **정보성**으로 처리되며, 해당 작업의 기본값은 조치 없음이며 요청별로 구성할 수 없습니다.
* `FUTURE_ISSUE_DATE`, `POOR_DOCUMENT_QUALITY`, `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`, `POA_MAX_ATTEMPTS_EXCEEDED`는 발생하지 않으며, 미래 날짜로 작성된 문서는 이 endpoint에서 자동으로 거부되지 **않습니다**.

요청 옵션에 대해서는 [POST /v3/poa/ API 레퍼런스](https://docs.didit.me/ko/standalone-apis/proof-of-address.md)를 참고하십시오.

## 재시도 동작(워크플로 세션)

인증 세션에서 주소 증명(POA) 업로드 단계는 문서가 수락되기 전에 차단 유효성 검사를 실행합니다. 차단 오류(`INVALID_DOCUMENT_TYPE`, `UNABLE_TO_EXTRACT_ISSUE_DATE`, `FUTURE_ISSUE_DATE`, `POA_NAME_NOT_DETECTED`, `MISSING_ADDRESS_INFORMATION`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNSUPPORTED_DOCUMENT_LANGUAGE` 또는 `POA_DOCUMENT_EXPIRED`)가 발견되면 `400`과 함께 위험 코드가 메시지로 반환되며 업로드가 거부되고 사용자는 더 나은 문서로 다시 시도할 수 있습니다.

`POA_DOCUMENT_EXPIRED`의 경우, `400` 응답 본문에 `expiration_reason`(`printed_expiration` 또는 `age_window`)도 포함되므로 UI에서 정확한 사유를 표시할 수 있습니다. `age_window` 경로에서는 `max_age_months`도 추가로 포함됩니다. `printed_expiration` 경로에서는 문서의 연령 기준이 아니라 인쇄된 만료일로 인해 거부되었으므로 `max_age_months`가 의도적으로 생략됩니다.

사용자가 `poa_max_retry_attempts` 시도 횟수(기본값 2, 구성 가능 2–5)를 모두 소진하면 제출이 그대로 수락됩니다. 저장된 문서에서 경고가 다시 계산되고, `POA_MAX_ATTEMPTS_EXCEEDED`가 추가되며, 전체 위험 세트로부터 상태가 결정됩니다. 이것이 바로 `FUTURE_ISSUE_DATE`가 업로드를 차단할 수는 있지만 `warnings[]`에는 나타나지 않는 이유입니다.

## 구성 가능한 설정

워크플로의 POA 노드는 다음과 같은 설정 항목(`VerificationSettings` 필드와 일치)을 제공합니다.

| 설정 | 제어 대상 | 기본값 |
| - | - | - |
| `poa_name_or_address_mismatch_action` | `NAME_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_ID_VERIFICATION`, `ADDRESS_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Review |
| `poa_document_issues_action` | `DOCUMENT_METADATA_MISMATCH` | Review |
| `poa_document_authenticity_action` | `SUSPECTED_DOCUMENT_MANIPULATION` | Decline |
| `poa_document_unproven_text_replacement_action` | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Review (검토를 전혀 수행하지 않는 워크플로는 자체 `poa_document_authenticity_action`이 Decline일 때 해당 값을 사용하며, 그렇지 않으면 No action을 사용합니다. 독립형 API는 요청의 `poa_document_authenticity_action`을 따릅니다) |
| `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | Decline |
| `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Decline |
| `poa_issuer_not_identified_action` | `ISSUER_NOT_IDENTIFIED` | Review |
| `poa_issue_date_not_detected_action` | `UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED` | Review |
| `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS` | Review |
| `poa_max_attempts_exceeded_action` | `POA_MAX_ATTEMPTS_EXCEEDED` | Decline |
| `poa_documents_allowed` | 국가별 허용 문서 유형, 각각 `enabled` 및 `age_months`(`-1` = 무제한) 포함. `document_subtypes_config`를 통한 하위 유형별 재정의 가능. | 공과금 고지서 및 은행 거래 내역서: 3개월, 정부 발급 및 기타: 12개월 |
| `poa_languages_allowed` | 허용된 문서 언어. | 지원되는 모든 언어 |
| `poa_name_match_score_threshold` | `NAME_MISMATCH*` 위험이 발생하기 전의 최소 이름 일치 점수(0–100). | 86 |
| `poa_max_retry_attempts` | 재시도 루프가 중단되기 전의 업로드 시도 횟수(2–5). | 2 |

## 이름 일치 로직

POA 이름 일치는 일반적인 변형을 허용합니다.

* **중간 이름 및 이니셜**은 유연하게 일치됩니다(포함/누락 허용).
* **후보 이름** — 문서에서 감지된 모든 이름(`name_on_document` 및 `additional_names`)에 대해 점수가 매겨지며, 가장 높은 점수를 받은 후보가 유지됩니다.
* **일치 임계값** — 기본 `poa_name_match_score_threshold`는 **86**입니다. 이보다 낮은 점수는 관련 `NAME_MISMATCH*` 경고를 트리거합니다.

숫자 점수는 보고서에 `name_match_score_expected_details` 및 `name_match_score_id_verification`(0–100)으로 표시됩니다. 점수 값은 경고가 발생하지 않은 경우에도 정밀한 검토에 유용합니다.

## 예시

### 오버레이 조작(기본값: 거부)

```json theme={null}
{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "SUSPECTED_DOCUMENT_MANIPULATION",
      "additional_data": {
        "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).",
        "detection_method": "overlay_text_manipulation",
        "signals": ["duplicate_font_subset", "glyph_fragmentation"],
        "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
        "fragmented_fonts": [],
        "manipulated_regions": [
          { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
        ]
      },
      "log_type": "error",
      "short_description": "Suspected document manipulation",
      "long_description": "The system detected signs of potential document manipulation or editing.",
      "node_id": "feature_poa_1"
    }
  ]
}
```

### 만료된 문서 및 주소 누락(자동 거부)

```json theme={null}
{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "POA_DOCUMENT_EXPIRED",
      "additional_data": {
        "expiration_reason": "age_window",
        "max_age_months": 3,
        "document_subtype": "ELECTRICITY_BILL",
        "document_type": "UTILITY_BILL",
        "issue_date": "2025-11-02"
      },
      "log_type": "error",
      "short_description": "Document expired",
      "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity.",
      "node_id": "feature_poa_1"
    },
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "MISSING_ADDRESS_INFORMATION",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Missing address information",
      "long_description": "The document does not contain complete or clear address information that can be extracted.",
      "node_id": "feature_poa_1"
    }
  ]
}
```

### 이름 불일치(기본값: 검토)

```json theme={null}
{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "NAME_MISMATCH_ID_VERIFICATION",
      "additional_data": {
        "poa_name": "JOHN B SMYTH",
        "kyc_name": "John A. Smith",
        "match_score": 60
      },
      "log_type": "warning",
      "short_description": "Name mismatch with ID verification",
      "long_description": "The full name on the document does not match the name from the user's verified identity documents.",
      "node_id": "feature_poa_1"
    }
  ]
}
```

## 관련 항목

* [주소 증명 보고서](https://docs.didit.me/ko/core-technology/proof-of-address/report-proof-of-address.md) — 전체 응답 형태, 오버레이 조작 포렌식, 상태 의미
* [주소 증명 개요](https://docs.didit.me/ko/core-technology/proof-of-address/overview.md) — 허용되는 문서 유형
* [데이터 모델 — 주소 증명](https://docs.didit.me/ko/reference/data-models.md#주소-증명) — 표준 스키마 및 Warning 객체
* [webhook](https://docs.didit.me/ko/integration/webhooks.md) — POA 경고를 전달하는 `status.updated`

### 경고 유형


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.