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

トランザクションモニタリングでよくある問題について、症状、原因、解決策をまとめたリファレンスです。

​

重複した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}/で取得するか、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を相手に実行され、environment: sandboxが付いたtravel_rule.status.updated Webhookが配信されます。ルールのモードにかかわらずrule_runsは空で返され、スコアは0のままです。また、期限切れとなるトラベルルール送金に対してtimeout_outcomeが適用されない限り、取引はAPPROVEDのままです。取引のレスポンスのenvironmentを確認してください。"sandbox"であれば、その取引は一度も評価されていません。本番運用前にルールを検証する方法は、サンドボックスでのトランザクションモニタリングを参照してください。
• ルールのモードが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クイックスタートと同じパターンに従います。完了時のWebhookを購読してください。
• 是正が完了しない場合に備え、古くなった取引を期限切れにするタイムアウトを自社システムに設定してください。

​

作成時のレート制限

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

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

レート制限を参照してください。

​

次のステップ