> ## 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 KYT에서 자주 발생하는 문제(txn_id 충돌, 규칙 미작동, AML 타임아웃, webhook 서명 불일치, 통화 문제)의 원인과 해결 방법을 정리합니다.

거래 모니터링에서 자주 발생하는 문제를 증상, 원인, 해결 방법과 함께 정리한 참조 자료입니다.

## `txn_id` 중복 오류

**증상.** 거래를 제출했을 때 `transaction_id` 필드에 `A transaction with this transaction_id already exists.` 메시지와 함께 `400`이 반환되거나, 동일한 요청 두 개가 경합할 때 `409`가 반환됩니다.

**원인.** `txn_id`(전송하는 `transaction_id`)는 애플리케이션마다 고유해야 합니다. Didit는 같은 `transaction_id`를 가진 두 번째 거래를 거부하며, 기존 레코드를 반환하지 않습니다.

**해결 방법.**

* 자체 시스템에서 `txn_id`를 결정론적으로 생성하십시오(예: 자체 거래 DB ID 사용).
* 재시도 중 중복 `transaction_id`에 대해 `400` 또는 `409`가 반환되면 요청을 다시 제출하지 말고 기존 거래를 조회하십시오. 첫 번째 응답의 `uuid`를 사용해 [`GET /v3/transactions/{uuid}/`](https://docs.didit.me/ko/management-api/transactions/get)로 읽거나, `transaction.created` webhook이 `txn_id`와 함께 전달하는 `transaction_id`(Didit uuid)를 사용하십시오.
* 재시도가 아닌 요청이라면 새 거래에 고유한 `transaction_id`를 부여하십시오.

## 규칙이 적용되지 않음

**증상.** 일치해야 하는 규칙을 만들었지만 `rule_runs[]`에서 `matched: true`로 표시되는 거래가 없습니다.

**원인과 해결 방법.**

* **애플리케이션이 샌드박스 모드임** - 샌드박스 애플리케이션은 규칙 평가, AML 스크리닝, 결제, `transaction.created` 및 `transaction.status.updated` webhook을 건너뜁니다. Travel Rule 교환은 활성화된 경우 여전히 실행되며, [Didit Test VASP](https://docs.didit.me/ko/transaction-monitoring/travel-rule-sandbox.md)를 대상으로 하고 `environment: sandbox`로 표시된 `travel_rule.status.updated` webhook을 전송합니다. 규칙 모드와 관계없이 `rule_runs`는 비어 있고 점수는 `0`으로 유지되며, 만료되는 Travel Rule 전송으로 인해 `timeout_outcome`이 적용되는 경우가 아니라면 거래는 `APPROVED` 상태로 남습니다. 거래 응답의 `environment`를 확인하십시오. `"sandbox"`이면 평가된 적이 없다는 뜻입니다. 실제 운영 전에 규칙을 검증하는 방법은 [샌드박스의 거래 모니터링](https://docs.didit.me/ko/integration/sandbox-testing.md#샌드박스의-거래-모니터링)을 참조하십시오.
* **규칙 모드가 `DISABLED` 또는 `TEST`임** - *Rules → \[rule] → Mode*에서 확인하십시오. 점수 산정에는 `ACTIVE` 규칙만 반영됩니다. `TEST` 규칙은 평가되지만 거래 상태에는 영향을 주지 않습니다.
* **범위 필터가 거래를 제외함** - 예를 들어 범위를 `transaction_type = finance`로 설정하면 `travelRule` 거래와 일치하지 않습니다.
* **집계 기간이 필요한 기간보다 짧음** - "30일 동안 20건의 거래" 규칙은 거래가 15건뿐일 때는 일치하지 않습니다.
* **조건 필드가 null임** - 예를 들어 규칙이 `counterparty.country_code`를 확인하지만 거래 상대방을 전송하지 않은 경우입니다.
* **통화 환산** - 규칙은 `amount_in_default_currency`를 기준으로 임계값을 확인합니다. 애플리케이션의 기본 통화가 거래 통화와 다르면 환산된 금액이 임계값보다 낮을 수 있습니다.

*Rules → \[rule] → Backtest* 기능을 사용하면 과거 거래를 다시 실행해 규칙이 실행되었거나 실행되지 않은 이유를 확인할 수 있습니다.

## 규칙이 거의 모든 거래에서 실행됨

**증상.** 규칙이 거래의 90% 이상에서 실행되어 검토 대기열이 넘쳐납니다.

**원인.** 조건이 지나치게 넓거나 임계값이 지나치게 낮습니다.

**해결 방법.**

* `scope` 필터를 추가해 적용 범위를 좁히십시오(예: 발신 거래만, 특정 거래 유형만).
* 임계값(금액, 거래 빈도)을 높이십시오.
* 규칙을 1주일 동안 `TEST` 모드로 두고 `rule_runs`를 분석해 일치율을 확인하십시오. 다시 활성화하기 전에 조건을 더 엄격하게 조정하십시오.

## 암호화폐 스크리닝 시간 초과

**증상.** 거래가 `status: APPROVED`로 완료되었지만 `provider_results[]` 배열에서 지갑, 트랜잭션 해시 또는 암호화폐 스크리닝 제공업체에 대해 `status: FAILED`가 표시됩니다.

**원인.**

* 제공업체 API를 일시적으로 사용할 수 없었습니다.
* 쿼리 시간이 초과되었습니다(보통 약 10초).

**해결 방법.**

* 제공업체 문제로 거래가 실패하는 경우는 없습니다. 데이터 보강은 최선의 노력으로 처리됩니다.
* 특정 제공업체가 반복적으로 실패하면 상태 페이지를 확인하거나 지원 티켓을 여십시오.
* *Settings → Transaction Monitoring → Providers*에서 제공업체 기본 설정을 구성해 다른 제공업체로 라우팅하는 것을 고려하십시오.

## IP 데이터 보강 누락

**증상.** 거래의 `applicant.ip_enrichment`가 없거나 일부만 있습니다.

**원인.**

* 제출 데이터에 `applicant.device.ip`가 없습니다.
* IP가 사설 또는 예약 주소이므로 라우팅할 수 없습니다.
* 모든 보강 제공업체를 일시적으로 사용할 수 없었습니다.

**해결 방법.**

* 클라이언트 또는 서버에서 제출자의 IP를 수집하고 모든 거래에 전달하십시오.
* 라우팅 가능한 IP만 사용하십시오. Didit는 사설 범위를 알림 없이 건너뜁니다.
* 콘솔의 *Settings → Status*에서 제공업체 상태를 확인하십시오.

## Webhook 서명 불일치

**증상.** 엔드포인트가 서명이 일치하지 않는다는 이유로 이벤트를 거부합니다.

**원인.**

* 원시 요청 본문이 변경되었습니다(JSON이 다른 공백으로 다시 직렬화됨).
* 잘못된 비밀 값을 사용했습니다.
* 동일한 URL을 가진 webhook 대상이 여러 개입니다. 서명은 대상마다 다릅니다.

**해결 방법.**

* **파싱된 JSON이 아니라 원시 요청 본문에 대해 서명을 계산하십시오.** 많은 프레임워크가 원시 본문 미들웨어를 제공합니다.
* 비밀 값이 노출되었다면 교체하십시오: *Webhook destinations → \[destination] → Rotate secret*.
* 비밀 값 혼동을 피하려면 URL마다 webhook 대상을 하나만 두십시오.

## Webhook이 도착하지 않음

**증상.** 거래는 생성되고 있지만 webhook이 전혀 도착하지 않습니다.

**원인.**

* 대상의 `enabled` 값이 `false`입니다.
* URL을 공개적으로 연결할 수 없습니다.
* 반복된 실패 후 대상이 자동으로 비활성화되었습니다.
* 이벤트가 `subscribed_events`에 없습니다.

**해결 방법.**

* 테스트 이벤트를 전송하십시오: *Webhook destinations → \[destination] → Send test*.
* 최근 전송 내역을 확인하십시오: *Webhooks → \[destination] → Deliveries*. 본문과 헤더가 포함된 4xx/5xx 응답을 확인할 수 있습니다.
* 비활성화된 대상은 다시 활성화하십시오.

## 통화 환산 결과가 잘못된 것 같음

**증상.** `amount_in_default_currency`가 예상한 환율과 일치하지 않습니다.

**원인.**

* FX 환율은 `txn_date` 기준의 중간 시장 환율입니다.
* 소급 적용된 거래는 해당 날짜의 과거 환율을 사용합니다.
* 일부 통화(이색 통화)는 업데이트 간격이 더 깁니다.

**해결 방법.**

* 표시에는 `amount`와 `currency`(원래 통화)를 사용하십시오.
* `amount_in_default_currency`는 내부 규칙 임계값 판단에만 사용하십시오.
* 감사를 위해 거래 레코드에는 평가 시점에 사용된 환산 환율이 고정되어 기록됩니다.

## 거래 상대방이 내 차단 목록과 일치하지 않음

**증상.** `vendor_data`로 기업을 차단 목록에 추가했지만, 해당 거래 상대방이 포함된 거래가 여전히 통과되었습니다.

**원인.**

* 거래 페이로드의 거래 상대방에 `vendor_data`가 없습니다. 외부 스냅샷으로 저장되어 있습니다.
* `vendor_data`의 대소문자가 다릅니다.

**해결 방법.**

* 거래 상대방이 플랫폼의 엔터티인 경우 항상 `counterparty.vendor_data`를 전달하세요.
* 모든 곳에서 같은 대소문자를 사용하세요. `vendor_data`는 대소문자를 구분합니다.

## AWAITING\_USER 거래가 멈춤

**증상.** 사용자가 조치 세션을 완료하지 않아 거래가 `AWAITING_USER` 상태에서 멈춰 있습니다.

**원인.**

* 사용자가 조치 세션 URL을 열지 않았습니다.
* 조치 세션이 만료되었습니다.
* 거래가 `travel-rule-pending-action`과 같은 라이브러리 규칙에 의해 `AWAITING_USER`로 전환된 Travel Rule 전송입니다. Didit는 Travel Rule 거래에 대해 기본 조치 세션을 생성하지 않으므로, 규칙에 별도의 조치 워크플로를 지정하지 않았다면 전달할 링크가 없습니다.

**해결 방법.**

* 거래 응답의 `remediation_session_url`이 전달할 링크입니다. 사용자에게 다시 전달하세요.
* Travel Rule 거래라면 **Travel Rule** 탭에서 해당 전송을 해결한 다음 거래 상태를 직접 변경하세요. 전송을 해결하는 것만으로는 거래가 `AWAITING_USER` 상태에서 자동으로 벗어나지 않습니다.
* 조치 세션은 [KYC 빠른 시작](https://docs.didit.me/ko/getting-started/quick-start.md) 가이드와 같은 방식을 따릅니다. 완료 webhook을 구독하세요.
* 조치가 완료되지 않을 경우 시스템에서 시간 초과 설정을 두어 오래된 거래를 만료시키세요.

## 생성 시 속도 제한

**증상.** 대용량 요청이 급증하는 동안 `429 Too Many Requests`가 발생합니다.

**해결 방법.**

* `Retry-After` 헤더를 준수하세요.
* 버스트 트래픽에 대해 클라이언트 측에서 요청 속도를 조절하세요.
* 검증된 프로덕션 거래량에 대해 더 높은 한도가 필요하면 지원팀에 문의하세요.

자세한 내용은 [속도 제한](https://docs.didit.me/ko/integration/rate-limiting.md)을 참조하세요.

## 다음 단계

> [card] [연동 가이드](https://docs.didit.me/ko/transaction-monitoring/integration-guide.md)
>
> 전체 연동 패턴을 확인하세요.

> [card] [규칙](https://docs.didit.me/ko/transaction-monitoring/rules.md)
>
> 규칙 평가가 작동하는 방식을 확인하세요.

> [card] [webhook](https://docs.didit.me/ko/transaction-monitoring/webhooks.md)
>
> webhook 작동 방식을 확인하세요.


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