> ## 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의 데이터베이스 검증에서 반환하는 결과 코드 전체 안내: 일치, 불일치, 사망자, 미성년자, 문서 미발견, 생체 정보 불일치. 건당 $0.05부터.

Didit의 [데이터베이스 검증](https://docs.didit.me/ko/core-technology/database-validation/overview.md) API는 아르헨티나의 RENAPER(생체 얼굴 대조 포함 검사당 \$0.20), 브라질의 Receita Federal(\$0.20), 파나마의 Tribunal Electoral SIB(생체 인증 \$0.75), 도미니카 공화국의 Junta Central Electoral(\$0.05) 및 그 외 14개국의 공식 주민등록 시스템을 조회하며, 월 최소 청구 금액 없이 성공한 조회 건당 비용이 청구됩니다.

데이터베이스 검증을 실행하면 두 가지 계층의 결과를 받게 됩니다.

1. 지원되는 모든 국가에서 동일한 방식으로 작동하는 **표준 결과 코드**로, 모든 국가를 아우르는 단일 처리 로직을 작성할 수 있습니다.
2. 정부 등록기관에서 반환한 정확한 상태를 알려주는 선택적 **국가별 세부 코드**로, 고객 지원, 분석 및 사용자에게 재시도를 유도할지 결정하는 데 유용합니다.

이 페이지에는 표시될 수 있는 모든 값과 각 값에 대응하는 방법이 나열되어 있습니다.

## 표준 결과 코드

이 코드들은 모든 국가에서 동일합니다. 국가별 세부 코드가 아닌, 이 코드들을 기반으로 검토, 거부 및 재시도 로직을 구축하세요.

| 결과 코드 | 의미 | 재시도 가능 여부 | 권장 처리 방법 |
| :- | :- | :-: | :- |
| `MATCH` | 등록기관에서 신원을 확인했으며 조회된 모든 필드가 일치했습니다. | — | 승인합니다. |
| `PARTIAL_MATCH` | 등록기관에서 기록을 찾았으나, 서비스에서 비교한 필드 중 하나 이상이 완전히 일치하지 않았습니다(주로 성명 또는 생년월일). 결과를 결정하는 필드는 서비스마다 다릅니다. [일치 확인 방법](https://docs.didit.me/ko/core-technology/database-validation/database-validation-matching-methods.md)을 참조하세요. | — | 검토로 보내거나 [Partial Match Action](https://docs.didit.me/ko/core-technology/database-validation/database-validation-warnings.md)을 구성하여 자동으로 거부합니다. |
| `NO_MATCH` | 등록기관에서 제출된 데이터와 일치하는 항목을 찾지 못했습니다. | 아니요 | 정책에 따라 거부하거나 검토로 보냅니다. |
| `DOCUMENT_SUPERSEDED` | 등록기관에서 해당 인물의 신원을 확인했으나, 제시된 **신분증의 발행본**이 등록기관에 보관된 버전과 다릅니다. 이후 더 새로운 에디션이 발급되었으므로 소지한 신분증은 최신 발행본이 아닙니다. 아르헨티나 DNI의 *ejemplar* 문자가 대표적인 사례입니다. `NO_MATCH`(인물 불일치) 및 `DOCUMENT_NOT_FOUND`(기록 없음)와는 다릅니다. 물리적 신분증만 최신 버전이 아닐 뿐입니다. | 아니요 | 검토로 보내고 최신 버전의 신분증을 요청하세요. 이 코드는 **No Match Action** 정책을 따르며 [`DATABASE_VALIDATION_DOCUMENT_SUPERSEDED`](https://docs.didit.me/ko/core-technology/database-validation/database-validation-warnings)를 발생시킵니다. |
| `DOCUMENT_NOT_FOUND` | 신분증 번호의 형식은 올바르지만 정부 등록기관에 존재하지 않습니다. | 아니요 | 거부합니다. |
| `INVALID_DOCUMENT_FORMAT` | 제출된 신분증 번호의 형식이 잘못되었습니다(잘못된 길이, 숫자가 아님, 잘못된 체크섬). | 아니요 | 사용자에게 신분증 번호를 다시 입력하도록 요청합니다. |
| `INVALID_INPUT` | 필수 입력 필드(셀피, 성별, 생년월일 등)가 누락되었거나 형식이 잘못되었습니다. | 아니요 | 사용자에게 누락된 필드를 다시 제출하도록 요청합니다. 데이터가 제공되면 세션이 자동으로 다시 처리됩니다. [`COULD_NOT_PERFORM_DATABASE_VALIDATION`](https://docs.didit.me/ko/core-technology/database-validation/database-validation-warnings)을 참조하세요. |
| `MINOR_BLOCKED` | 대상자가 미성년자이므로 등록기관에서 기록 제공을 보류했습니다. 미성년자 데이터 보호법이 있는 관할 구역(브라질 LGPD, 아르헨티나)에 적용됩니다. | 아니요 | 거부합니다. 현지 법적 체계를 준수하고 재시도하지 마세요. |
| `DECEASED` | 등록기관에 대상자가 사망자로 보고되어 있습니다. | 아니요 | 거부합니다. |
| `BIOMETRIC_NO_MATCH` | 생체 검증(아르헨티나, 파나마)의 경우, 얼굴 대조 점수가 허용 임계값 미만이었습니다. | 아니요 | 거부하거나 검토로 보냅니다. |
| `BIOMETRIC_IMAGE_UNUSABLE` | 이미지가 비어 있거나, 얼굴이 없거나, 화질이 낮거나, 등록기관에서 읽을 수 없어 셀피를 처리할 수 없었습니다. | 예 | 사용자에게 셀피를 다시 촬영하도록 유도합니다. |
| `INCONCLUSIVE` | 등록기관에서 해당 인물의 일치 여부를 판단할 수 없었습니다. 결과가 불확실합니다(등록기관에 존재할 수도 있고 존재하지 않을 수도 있음). `NO_MATCH`(확정적인 미등록) 및 `BIOMETRIC_IMAGE_UNUSABLE`(기술적인 이미지 문제)과는 다릅니다. 어느 쪽으로도 확인되지 않았으므로 `match_type`은 `null`입니다. | 경우에 따라 가능 | 검토로 보냅니다. 더 선명한 셀피나 추가 데이터를 사용해 재시도하면 해결될 수 있습니다. |
| `REGISTRY_UNAVAILABLE` | 정부 등록기관에 일시적으로 접속할 수 없습니다(시간 초과, 연결 오류, 상위 시스템 5xx). | 예 | 잠시 후 다시 시도합니다. Didit은 이미 일시적 오류를 자동으로 재시도하므로 최종 보고서에 이 오류가 표시된다면 재시도 횟수를 모두 소진했음을 의미합니다. 등록기관 장애가 계속되는 경우, 중단이 지속될 때 조직에 이메일이 발송되며 접근이 복구되면 다시 발송됩니다. [가용성 알림](https://docs.didit.me/ko/core-technology/database-validation/overview.md#가용성-알림)을 참조하세요. |
| `REGISTRY_ERROR` | 등록기관에서 위의 범주에 맞지 않는 예기치 않은 오류를 반환했습니다. | 경우에 따라 가능 | 세부 코드와 함께 고객 지원 팀에 에스컬레이션하세요. |

> [!NOTE]
>
> `outcome_code`는 검증 보고서의 `validations` 배열 내 각 항목에 포함됩니다. 응답 내 위치는 [데이터베이스 검증 보고서](https://docs.didit.me/ko/core-technology/database-validation/database-validation-report.md)를 참조하세요.

> [!NOTE]
>
> `REGISTRY_UNAVAILABLE` 및 `REGISTRY_ERROR`는 소스 등록기관이 쿼리에 응답하지 않았음을 의미하므로, 이 두 가지 결과는 **비용이 청구되지 않습니다**. [요금](https://docs.didit.me/ko/core-technology/database-validation/overview.md)을 참조하세요. 다른 모든 결과 코드는 아무것도 확인되지 않은 경우(`INCONCLUSIVE`, `BIOMETRIC_IMAGE_UNUSABLE`)나 전송한 데이터가 거부된 경우(`INVALID_DOCUMENT_FORMAT`, `INVALID_INPUT` - 결과 코드로 나타난다는 것은 쿼리가 전송된 후 등록기관 자체에서 데이터를 거부했음을 의미함)라도 등록기관의 실제 유료 응답입니다.
>
> 등록기관에 도달하지 않은 입력은 결과 코드를 전혀 생성하지 않습니다. 값이 국가 형식 규칙을 충족하지 못하면 `POST /v3/database-validation/`은 `400`을 반환하며, 누락되거나 형식이 잘못된 필드가 있는 워크플로 서비스는 [`COULD_NOT_PERFORM_DATABASE_VALIDATION`](https://docs.didit.me/ko/core-technology/database-validation/database-validation-warnings)과 함께 건너뜁니다. 두 경우 모두 비용이 청구되지 않습니다. 자세한 내용은 [데이터베이스 검증 요금 페이지](https://docs.didit.me/ko/getting-started/database-validation-pricing.md)를 참조하세요.

## 국가별 상세 코드

상세 코드는 `outcome_code`와 함께 `outcome_detail`로 반환됩니다. 아래 나열된 국가만 표준 결과 외의 상세 코드를 생성하며, 지원되는 다른 모든 국가는 표준 코드만 반환합니다.

### 아르헨티나 (RENAPER)

아르헨티나는 RENAPER 국립 신원 등록부를 대상으로 DNI, 셀피, 신고된 성별을 결합하여 생체 인식 1×1 검증을 사용합니다.

| 상세 코드 | 표준 결과 | 의미 |
| :- | :- | :- |
| `300` | `INVALID_DOCUMENT_FORMAT` | DNI 필드는 7\~8자리 숫자여야 합니다. |
| `301` | `DOCUMENT_NOT_FOUND` | 제출된 DNI가 유효한 기록과 일치하지 않습니다. |
| `303` | `INVALID_INPUT` | 셀피 필드가 비어 있습니다. |
| `304` | `INVALID_INPUT` | 성별 필드가 비어 있거나 `M`, `F`, `X` 중 하나가 아닙니다. |
| `305` | `NO_MATCH` | DNI와 성별 조합을 찾을 수 없습니다. |
| `306` | `REGISTRY_UNAVAILABLE` | 현재 조회를 수행할 수 없습니다. |
| `307` | `REGISTRY_UNAVAILABLE` | 공공 신원 검증 시스템 연결 오류입니다. |
| `311` | `REGISTRY_ERROR` | 연동에 이 제품에 대한 접근 권한이 없습니다. |
| `313` | `MINOR_BLOCKED` | 미성년자의 기록입니다. |
| `400` | `REGISTRY_UNAVAILABLE` | 연결 오류입니다. |
| `401` | `NO_MATCH` | 제공된 데이터에 대한 결과를 찾을 수 없습니다. |
| `405` | `BIOMETRIC_IMAGE_UNUSABLE` | 이미지 충돌이 발생하여 처리할 수 없습니다. |
| `406` | `BIOMETRIC_IMAGE_UNUSABLE` | 이미지 처리 오류입니다. |
| `NO.HIT` | `BIOMETRIC_NO_MATCH` | 얼굴 대조 점수가 허용 임계값 미만입니다(\< 50). |
| `INTERNAL_ERROR` | `REGISTRY_UNAVAILABLE` | 시간 초과가 발생했습니다. |

### 브라질 (Receita Federal — Consulta CPF)

브라질은 Receita Federal의 공식 CPF 서비스를 통해 CPF를 검증하며, LGPD(Lei Geral de Proteção de Dados) 및 아동·청소년 디지털 법령에 따라 미성년자를 명시적으로 처리합니다.

| 상세 코드 | 표준 결과 | 의미 |
| :- | :- | :- |
| `200` | `MATCH` | CPF를 찾았으며 데이터가 성공적으로 반환되었습니다. |
| `206` | `MATCH` | CPF를 찾았으나 일부 필수적이지 않은 필드가 반환되지 않았습니다. |
| `400` | `INVALID_DOCUMENT_FORMAT` | CPF 번호가 유효하지 않습니다. |
| `404` | `DOCUMENT_NOT_FOUND` | 제출된 번호와 일치하는 CPF가 존재하지 않습니다. |
| `422` | `MINOR_BLOCKED` | LGPD(법률 13.709/2018)에 따라 만 18세 미만 미성년자의 데이터가 제공되지 않습니다. 응답에 `minor_under_18: true`가 포함됩니다. |
| `451` | `MINOR_BLOCKED` | LGPD 및 아동·청소년 디지털 법령(법률 15.211/2025)에 따라 만 16세 미만 미성년자의 데이터가 제공되지 않습니다. 응답에 `minor_under_18: true` 및 `minor_under_16: true`가 포함됩니다. |
| `500` | `REGISTRY_UNAVAILABLE` | 업스트림 서버 오류입니다. |
| `504` | `REGISTRY_UNAVAILABLE` | 게이트웨이 타임아웃입니다. 요청이 Consulta CPF API에 도달하지 못했습니다. |

> [!NOTE]
>
> 브라질의 `MINOR_BLOCKED` 결과의 경우, `source_data`에서 `lgpd_minor`, `minor_under_18`, `minor_under_16` 플래그를 계속 반환하므로 재시도 없이 연령에 적합한 흐름을 적용할 수 있습니다.

### 파나마 (SIB — Tribunal Electoral)

파나마는 Tribunal Electoral에서 운영하는 SIB(Servicio de Identificación Biométrica) 등록부를 대상으로 생체 인식 검증을 사용합니다. 기술적인 SIB 오류가 발생하면 세션은 자동으로 1×1 조회로 대체됩니다.

| 상세 코드 | 표준 결과 | 의미 |
| :- | :- | :- |
| `601` | `REGISTRY_UNAVAILABLE` | 데이터베이스에 운영자가 존재하지 않습니다. |
| `602` | `MINOR_BLOCKED` | 시민이 만 12세 미만입니다. |
| `603` | `DECEASED` | 시민이 사망했습니다. |
| `604` | `NO_MATCH` | 시민의 등록 정보가 유효하지 않습니다. |
| `605` | `NO_MATCH` | 시민을 식별할 수 없습니다. |
| `606` | `INVALID_INPUT` | Cédula 필드가 비어 있습니다. |
| `607` | `DOCUMENT_NOT_FOUND` | 시민을 찾을 수 없습니다. |
| `608` | `REGISTRY_ERROR` | 이 고객에게 SIB 접근 권한이 없습니다. |
| `610` | `BIOMETRIC_IMAGE_UNUSABLE` | 일반 안면 검증 오류입니다. |
| `611` | `BIOMETRIC_IMAGE_UNUSABLE` | 비교용 이미지가 전송되지 않았습니다. |
| `612` | `BIOMETRIC_IMAGE_UNUSABLE` | 이미지에 내용이 없습니다. |
| `613` | `BIOMETRIC_IMAGE_UNUSABLE` | 유효하지 않은 이미지 형식입니다. |
| `614` | `BIOMETRIC_IMAGE_UNUSABLE` | 이미지에서 얼굴이 감지되지 않았습니다. |
| `615` | `BIOMETRIC_NO_MATCH` | 유사도 임계값에 도달하지 못했습니다. |

### 기타 지원 국가

아래 국가들은 표준 결과 코드만 반환하며, 처리해야 할 국가별 상세 코드가 없습니다.

* **볼리비아, 콜롬비아, 코스타리카, 엘살바도르, 과테말라, 온두라스, 파라과이, 스페인, 우루과이, 베네수엘라** — 해당 시민 등록부를 대상으로 한 1×1 조회입니다. 결과는 `MATCH`, `NO_MATCH`, `DOCUMENT_NOT_FOUND`, `INVALID_DOCUMENT_FORMAT` 또는 `REGISTRY_UNAVAILABLE`에 직접 매핑됩니다.
* **칠레 (Registro Civil)** — RUT 조회입니다. 표준 결과에 매핑되며 등록부에서 미성년자 기록으로 표시할 경우 `MINOR_BLOCKED`가 추가됩니다.
* **도미니카 공화국 (JCE)** — 불리언 유효성을 반환하는 Cédula 조회이며, `MATCH` 또는 `NO_MATCH`에 매핑됩니다.
* **에콰도르 (Registro Civil)** — Cédula 조회입니다.
* **멕시코 (RENAPO 및 2×2용 INE)** — RENAPO를 통한 CURP 조회입니다. `validation_type`이 `two_by_two`인 경우 추가 INE 교차 참조가 실행되며, 둘 다 동일한 표준 결과 코드로 반영됩니다.
* **페루 (RENIEC)** — DNI 조회입니다.

## 처리 방법 예시

가장 간단하고 견고한 핸들러는 다음과 같습니다.

```typescript theme={null}
switch (result.outcome_code) {
  case "MATCH":
    return approve();
  case "PARTIAL_MATCH":
    return review();
  case "NO_MATCH":
  case "DOCUMENT_NOT_FOUND":
  case "DECEASED":
  case "MINOR_BLOCKED":
  case "BIOMETRIC_NO_MATCH":
    return decline();
  case "INVALID_DOCUMENT_FORMAT":
  case "INVALID_INPUT":
    return askUserToFixInput(result.outcome_detail);
  case "BIOMETRIC_IMAGE_UNUSABLE":
    return askUserToRetakeSelfie();
  case "REGISTRY_UNAVAILABLE":
  case "REGISTRY_ERROR":
    return review();  // Didit already retried; a human can decide.
  default:
    return review();
}
```

> [!NOTE]
>
> 비즈니스 로직을 위해 `outcome_detail`로 분기할 필요는 없으며, 분석, 디버깅 및 지원 티켓용으로 사용하십시오. 표준 `outcome_code`는 국가와 시간에 관계없이 항상 안정적으로 유지됩니다.

## 관련 문서

* [데이터베이스 검증 경고](https://docs.didit.me/ko/core-technology/database-validation/database-validation-warnings.md) — 세션 수준 경고 태그(`COULD_NOT_PERFORM_DATABASE_VALIDATION`, `DATABASE_VALIDATION_PARTIAL_MATCH`, `DATABASE_VALIDATION_NO_MATCH`) 및 애플리케이션의 검토/거부 작업을 구성하는 방법입니다.
* [데이터베이스 검증 보고서](https://docs.didit.me/ko/core-technology/database-validation/database-validation-report.md) — 전체 응답 구조와 `outcome_code` / `outcome_detail`이 표시되는 위치입니다.
* [데이터베이스 검증 지원 국가](https://docs.didit.me/ko/core-technology/database-validation/database-validation-supported-countries.md) — 전체 국가 및 일치 방식 목록입니다.


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