> ## 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.

# KYTトラブルシューティング：よくある問題と解決方法

> 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`を持つ2件目の取引を拒否し、既存のレコードは返しません。

**解決策**

* `txn_id`は自社側で決定的に生成してください(例:自社の取引DBのIDを使用する)。
* 再試行中に重複した`transaction_id`で`400`または`409`が返された場合は、再送信せずに既存の取引を参照してください。最初のレスポンスに含まれる`uuid`を使って[`GET /v3/transactions/{uuid}/`](https://docs.didit.me/ja/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がスキップされます。トラベルルールのやり取りは有効にしていれば引き続き[Didit Test VASP](https://docs.didit.me/ja/transaction-monitoring/travel-rule-sandbox.md)を相手に実行され、`environment: sandbox`が付いた`travel_rule.status.updated` Webhookが配信されます。ルールのモードにかかわらず`rule_runs`は空で返され、スコアは`0`のままです。また、期限切れとなるトラベルルール送金に対して`timeout_outcome`が適用されない限り、取引は`APPROVED`のままです。取引のレスポンスの`environment`を確認してください。`"sandbox"`であれば、その取引は一度も評価されていません。本番運用前にルールを検証する方法は、[サンドボックスでのトランザクションモニタリング](https://docs.didit.me/ja/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はプライベートIPアドレス帯を通知せずに無視します。
* コンソールの*Settings → Status*でプロバイダーの稼働状況を確認してください。

## Webhook署名の不一致

**症状**:署名が一致しないため、エンドポイントがイベントを受け付けません。

**原因**

* 生のボディが変更された（異なる空白でJSONを再度文字列化した）。
* シークレットが間違っている。
* 同じURLを持つWebhookの送信先が複数ある。署名は送信先ごとに異なります。

**解決策**

* 解析済みのJSONではなく、**生のリクエストボディに対して署名を計算してください**。多くのフレームワークには生のボディを扱うミドルウェアがあります。
* シークレットが漏えいした場合はローテーションしてください:*Webhook destinations → \[destination] → Rotate secret*。
* シークレットの混同を避けるため、1つのURLにつきWebhookの送信先は1つにしてください。

## Webhookが届かない

**症状**:取引は作成されているのに、Webhookがまったく届きません。

**原因**

* 送信先の`enabled`が`false`になっている。
* URLに外部からアクセスできない。
* 失敗が繰り返されたため、送信先が自動的に無効化された。
* イベントが`subscribed_events`に含まれていない。

**解決策**

* テストイベントを送信してください:*Webhook destinations → \[destination] → Send test*。
* 最近の配信を確認してください:*Webhooks → \[destination] → Deliveries*。4xx/5xxのレスポンスをボディとヘッダー付きで確認できます。
* 無効化された送信先を再度有効にしてください。

## 通貨換算が正しくないように見える

**症状。**`amount_in_default_currency`が想定しているレートと一致しません。

**原因。**

* 為替レートは`txn_date`時点の仲値です。
* 過去の日付の取引には、その日付時点のレートが使用されます。
* 一部の通貨（エキゾチックFX）は更新間隔が粗くなっています。

**解決策。**

* 表示には`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`に移行された。Didit はトラベルルールの取引に対してデフォルトの是正セッションを作成しないため、ルールで独自の是正ワークフローを指定していない限り、配信するリンクが存在しません。

**対処法。**

* 取引レスポンスの`remediation_session_url`が配信すべきリンクです。ユーザーに再配信してください。
* トラベルルールの取引の場合は、その送金の「**Travel rule**」タブで送金を解決したうえで、取引のステータスをご自身で変更してください。送金を解決しただけでは、取引は`AWAITING_USER`から移行しません。
* 是正セッションは[KYCクイックスタート](https://docs.didit.me/ja/getting-started/quick-start.md)と同じパターンに従います。完了時のWebhookを購読してください。
* 是正が完了しない場合に備え、古くなった取引を期限切れにするタイムアウトを自社システムに設定してください。

## 作成時のレート制限

**症状。** 大量のリクエストが集中した際に`429 Too Many Requests`が返される。

**対処法。**

* `Retry-After`ヘッダーに従ってください。
* 集中的なトラフィックに対しては、クライアント側でスロットリングを行ってください。
* 本番環境で実績のある利用量に基づいて上限の引き上げを希望する場合は、サポートにお問い合わせください。

[レート制限](https://docs.didit.me/ja/integration/rate-limiting.md)を参照してください。

## 次のステップ

> [card] [連携ガイド](https://docs.didit.me/ja/transaction-monitoring/integration-guide.md)
>
> 連携パターンの全体像。

> [card] [ルール](https://docs.didit.me/ja/transaction-monitoring/rules.md)
>
> ルール評価の仕組み。

> [card] [Webhook](https://docs.didit.me/ja/transaction-monitoring/webhooks.md)
>
> Webhookの仕組み。


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