> ## 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 데이터베이스 검증의 모든 경고 및 코드 레퍼런스입니다. COULD_NOT_PERFORM_DATABASE_VALIDATION, 부분 일치 및 불일치, 레지스트리 연결 불가, 필드 누락 등을 다룹니다.

Didit의 [데이터베이스 검증](https://docs.didit.me/ko/core-technology/database-validation/overview.md) 기능은 공신력 있는 주민등록기관(아르헨티나의 RENAPER, 브라질의 Receita Federal, 파나마의 Tribunal Electoral(생체 인식), 도미니카 공화국의 Junta Central Electoral 등)을 통해 신원 데이터를 검증하며, 월 최소 청구 금액 없이 성공한 쿼리 건당 청구됩니다.

어떤 서비스도 실행될 수 없거나(필수 필드 누락 또는 형식 오류, 등록기관 사용 불가), 문서 자체를 확인할 수 없거나(구성된 서비스에 필요한 식별자가 없는 경우 — 예: 주민등록번호가 없는 여권), 종합된 결과가 확정적이지 않은 경우(부분 일치, 일치하지 않음) 해당 기능은 세션에 **경고**를 발생시킵니다. 워크플로에서 발급 국가가 아예 활성화되어 있지 않은 경우, 이 단계는 경고나 비용 청구 없이 건너뜁니다. 이 페이지에서는 모든 경고 코드, 트리거 조건 및 워크플로 응답 구성 방법을 설명합니다.

## 개요

경고는 워크플로 세션과 독립형 API(`POST /v3/database-validation/`) 모두에서 생성됩니다. 5가지 위험은 모두 `DATABASE_VALIDATION` 기능으로 태그 지정되며 보고서의 `database_validations[].warnings[]` 아래에 표시되고, 표준 [경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체) 형식(`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`)을 따릅니다.

데이터베이스 검증에는 강제 자동 거부 트리거가 없습니다. 두 가지 일치 결과 위험, 대체된 문서 위험, 해당 없음 위험은 **구성 가능한 작업**(`DECLINE`, `REVIEW` 또는 `NO_ACTION`)에 매핑됩니다. `COULD_NOT_PERFORM_DATABASE_VALIDATION`은 유일하게 고정된 동작으로, 기능을 항상 **검토 중**으로 라우팅합니다.

## 구성 가능한 위험

| 설정 | 위험 코드 | 동작 |
| - | - | - |
| 일치 없음 작업 | `DATABASE_VALIDATION_NO_MATCH` | `REVIEW`(워크플로 기본값)는 해당 기능을 **검토 중**으로 설정합니다. `DECLINE`은 거부합니다. `NO_ACTION`은 상태에 영향을 주지 않고 경고를 기록합니다. 독립형 API의 `no_match_action` 파라미터는 기본값이 `DECLINE`입니다. |
| 부분 일치 작업 | `DATABASE_VALIDATION_PARTIAL_MATCH` | `NO_ACTION`(기본값)은 상태에 영향을 주지 않고 경고를 기록합니다. `REVIEW`는 해당 기능을 **검토 중**으로 설정합니다. `DECLINE`은 거부합니다. |
| 일치 없음 작업 | `DATABASE_VALIDATION_DOCUMENT_SUPERSEDED` | **일치 없음 작업** 설정을 공유하며 별도의 설정 항목은 없습니다. 등록기관의 정보가 제출된 내용과 모순되므로, 일치하지 않을 때 거부하는 조직은 오래된 자격 증명도 거부하게 됩니다. |
| 해당 없음 작업 | `DATABASE_VALIDATION_NOT_APPLICABLE` | `NO_ACTION`(기본값)은 상태에 영향을 주지 않고 경고를 기록합니다. `REVIEW`는 해당 기능을 **검토 중**으로 설정합니다. `DECLINE`은 거부합니다. 문서 자체를 전혀 확인할 수 없을 때(구성된 서비스가 조회하는 식별자가 없는 경우, 예: 주민등록번호가 없는 여권) 발생합니다. |

구성된 작업은 경고의 `log_type`도 결정합니다: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

일치 결과 자체는 서비스별 `validation` 항목에서 종합됩니다(완전 일치가 하나라도 있는 경우 → `full_match`, 그 외 부분 일치가 있는 경우 → `partial_match`, 그 외 → `no_match`). 1×1 / 2×2 결과를 도출하는 전체 결정 로직은 [매칭 방법](https://docs.didit.me/ko/core-technology/database-validation/database-validation-matching-methods.md)을 참고하세요.

## 생성되는 경고

| 태그 | 간단한 설명 | 설명 |
| - | - | - |
| `COULD_NOT_PERFORM_DATABASE_VALIDATION` | 데이터베이스 검증을 수행할 수 없음 | 어떤 서비스도 사용 가능한 결과를 반환하지 않았습니다(`match_type`은 `null`로 유지됨). 일반적으로 필수 필드가 누락되었거나 형식이 잘못되었거나, 등록부에서 오류를 반환했기 때문입니다. `additional_data`에는 서비스별 건너뛰기 요약(`reason`, `database_validation_errors`, `missing_required_fields_by_service`, `invalid_format_fields_by_service`, `field_reasons_by_service`)이 포함되며, 독립형 API에서는 대신 `{ "validation_errors": [...] }`를 사용합니다. 이 경고가 발생해도 **요금이 청구되지 않으며**, 데이터가 수정될 때까지 해당 기능은 **검토 중** 상태로 이동합니다. |
| `DATABASE_VALIDATION_NOT_APPLICABLE` | 이 문서에는 데이터베이스 검증을 적용할 수 없음 | 제공된 문서에 구성된 데이터베이스 서비스에서 요구하는 식별자가 포함되어 있지 않습니다(`match_type`은 `null`로 유지됨). 예를 들어 브라질 여권에는 CPF가 없으므로 CPF 등록부를 조회할 수 없습니다. 이는 해당 문서 유형에서 예상되는 동작이며 문서 자체의 문제를 나타내지는 않습니다. `additional_data`에는 서비스별 건너뛰기 요약이 포함됩니다. 이 경고가 발생해도 **요금이 청구되지 않습니다**. 작업은 구성 가능합니다(기본값 `NO_ACTION`). |
| `DATABASE_VALIDATION_PARTIAL_MATCH` | 데이터베이스 검증 부분 일치 | 종합 `match_type`이 `partial_match`입니다. 검사된 일부 필드가 등록부와 일치하지만 전체가 일치하지는 않습니다. 작업은 구성 가능합니다(기본값 `NO_ACTION`). |
| `DATABASE_VALIDATION_NO_MATCH` | 데이터베이스 검증 불일치 | 종합 `match_type`이 `no_match`입니다. 등록부에서 검사된 신원을 확인할 수 없습니다. 작업은 구성 가능합니다(워크플로에서는 기본값 `REVIEW`, 독립형 API에서는 `DECLINE`). |
| `DATABASE_VALIDATION_DOCUMENT_SUPERSEDED` | 대체된 문서 버전 | 서비스가 `DOCUMENT_SUPERSEDED`를 반환했습니다. 등록부에서 해당 인물을 확인했으나, 제시된 문서의 버전이 기록된 것과 일치하지 않으며 그 이후 더 최신 버전이 발급되었습니다. 모든 개인 필드가 일치하여 `full_match`로 유지되는 `match_type`과 독립적으로 발생하며, 그렇지 않으면 이 결과를 감지할 수 없습니다. `additional_data`에 이를 보고한 서비스가 표시됩니다. **No Match Action** 설정을 따릅니다. |

> [!NOTE]
>
> `COULD_NOT_PERFORM_DATABASE_VALIDATION`은 두 가지 서로 다른 상황을 다루며, 경고의 `long_description`(및 서비스별 실패의 경우 `database_validation_errors[].message`)에 단일 일반 문장 대신 둘 중 어느 상황이 적용되었는지가 명시됩니다. 즉, 서비스를 조회하기 전에 검사 데이터가 누락되었거나 형식이 잘못되었는지, 아니면 서비스를 조회했으나 사용 가능한 결과를 반환하지 않았는지 표시됩니다. 두 번째 경우, 등록부가 해당 시도에 대해 자체 진단 세부 정보를 보고한 경우 그 세부 정보가 메시지에 포함되므로 지원팀에 문의하지 않고도 원인을 파악할 수 있습니다. 업스트림 서비스의 이름은 응답에 포함되지 않습니다.

> [!NOTE]
>
> 워크플로 세션에서 `COULD_NOT_PERFORM_DATABASE_VALIDATION` 또는 `DATABASE_VALIDATION_NOT_APPLICABLE`이 발생하면, 콘솔의 세션 상세 페이지에서 누락된 데이터를 입력했을 때 검사가 자동으로 다시 트리거됩니다. 필드를 저장하면 검증이 다시 실행되고, 성공하면 경고가 제거됩니다. 이는 해당 없음 작업으로 인해 세션이 거부된 경우에도 작동하므로, 데이터를 수정하여 거부된 세션을 바로잡을 수 있습니다. `DATABASE_VALIDATION_NOT_APPLICABLE`의 경우, 문서에 식별자가 포함될 수 있지만 인식되지 않은 경우(예: 국가 신분증 번호가 추출되지 않은 거주증) 재실행이 유용합니다. 식별자가 전혀 포함되지 않는 문서 유형(예: 국가 신분증 번호가 없는 여권)은 경고가 유지됩니다. 건너뛴 서비스에는 **요금이 청구되지 않으며**, 서비스가 청구 가능한 결과를 반환하는 경우에만 비용을 지불합니다.

## 예시

```json theme={null}
{
  "warnings": [
    {
      "feature": "DATABASE_VALIDATION",
      "risk": "DATABASE_VALIDATION_NO_MATCH",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Database validation no match",
      "long_description": "The system identified a no match in the database validation, requiring further investigation.",
      "node_id": "feature_db_validation_1"
    }
  ]
}
```

## 경고 유형

각 위험에는 애플리케이션 설정을 기반으로 심각도가 할당됩니다. 심각도는 세 가지 범주로 나뉩니다.

## 관련 항목

* [데이터베이스 검증 개요](https://docs.didit.me/ko/core-technology/database-validation/overview.md) — 엔드투엔드 기능 작동 방식 및 지원되는 등록부.
* [데이터베이스 검증 보고서](https://docs.didit.me/ko/core-technology/database-validation/database-validation-report.md) — 서비스별 `validations[]`를 포함한 전체 응답 형태.
* [일치 방식](https://docs.didit.me/ko/core-technology/database-validation/database-validation-matching-methods.md) — 서비스별 일치 결과로부터 1×1 / 2×2 결과(`validation_type: one_by_one` / `two_by_two`)가 도출되는 방식.
* [결과 코드](https://docs.didit.me/ko/core-technology/database-validation/database-validation-outcome-codes.md) — 국가별 세부 코드가 포함된 전체 결과별 분류.
* [지원 국가 및 서비스](https://docs.didit.me/ko/core-technology/database-validation/database-validation-supported-countries.md) — 모든 운영 중인 등록부, 필수 필드 및 호출당 가격.
* [데이터 모델 — 데이터베이스 검증](https://docs.didit.me/ko/reference/data-models.md#데이터베이스-검증) — 표준 필드별 스키마.


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