> ## 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 电话验证的全部风险代码：HIGH_RISK_PHONE_NUMBER、VOIP_NUMBER_DETECTED、DISPOSABLE_NUMBER_DETECTED、黑名单及一次性验证码上限。

电话验证功能会在 OTP 流程或号码本身触发风险信号时发出**警告**：已知不良号码、VoIP 或一次性线路、超出 OTP 尝试次数上限，或命中另一用户的会话。本页面列出了每个代码、触发条件以及如何配置工作流响应。

## 概述

警告标记有功能标识 `PHONE`。它们显示在 `GET /v3/session/{sessionId}/decision/` 中的 `phone_verifications[].warnings[]` 下，并遵循标准[警告对象](https://docs.didit.me/zh/reference/data-models.md#警告对象)结构（`feature`、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`、`node_id`）。每个警告还会路由到每个会话的日志中，从而在 Business Console 的电话部分显示。

某些警告属于**硬性自动拒绝**触发器：它们始终将功能状态设置为 `Declined`。其他警告则映射到工作流设置中定义的**可配置操作**（取决于具体设置，可为 `DECLINE`、`REVIEW` 或 `NO_ACTION`），因此相同的风险代码可能会拒绝某个工作流，而在另一个工作流中仅进行标记。

## 自动拒绝条件

以下警告无论如何配置都始终会拒绝电话验证步骤，并始终带有 `log_type: "error"`：

* `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`：用户用尽了 OTP 尝试次数上限：默认为 2 次错误验证码提交（`phone_max_check_attempts`）或超过 2 次 OTP 发送（`phone_max_retries`），两者均可在每个工作流节点中调整。独立电话 API 允许 3 次验证码尝试。
* `PHONE_NUMBER_IN_BLOCKLIST`：该号码位于您通过 [Lists API](https://docs.didit.me/zh/management-api/lists/overview.md) 管理的黑名单中，或者与已被列入黑名单的会话相匹配。

`HIGH_RISK_PHONE_NUMBER`（投递服务商的反欺诈层拒绝发送 OTP，即 `Blocked` 发送）默认拒绝，但**不再是无条件的**：参见下文的 [`high_risk_phone_action`](#被拦截的发送)。

## 可配置风险

以下各项风险均映射到一个工作流设置，您可以将其配置为 `DECLINE`、`REVIEW` 或 `NO_ACTION`（默认值，记录警告但不影响状态）。配置的操作还会设置警告的 `log_type`：`DECLINE` → `error`，`REVIEW` → `warning`，`NO_ACTION` → `information`。

| 设置 | 风险代码 | 触发条件 |
| - | - | - |
| `voip_number_action` | `VOIP_NUMBER_DETECTED` | 运营商解析为 `voip`、`isp` 或 `vpn` 线路类型。 |
| `disposable_number_action` | `DISPOSABLE_NUMBER_DETECTED` | 查询将该号码标记为临时/一次性号码提供商。 |
| `duplicated_phone_number_action` | `DUPLICATED_PHONE_NUMBER` | 该号码与属于不同终端用户的任何状态的另一会话相匹配。当该号码处于白名单时跳过。 |

重复检测在您的应用内跨 KYC、KYB 和独立 API 电话验证运行，并按 `vendor_data` 对会话进行分组；共享相同 `vendor_data` 的会话将被视为同一终端用户，并从匹配结果中排除。如果将 `vendor_data` 留空，则每个会话都将被视为不同用户。

### 被拦截的发送

`HIGH_RISK_PHONE_NUMBER` 遵循相同的模式，但可选项范围较窄，因为服务商拒绝的发送无法被批准：

| 设置 | 风险代码 | 触发条件 |
| - | - | - |
| `high_risk_phone_action` | `HIGH_RISK_PHONE_NUMBER` | 投递服务商的反欺诈层拒绝发送 OTP（`Blocked` 发送）。仅接受 `DECLINE` 或 `REVIEW`，默认为 `DECLINE`。 |

该设置**仅在该步骤上的每个高风险拦截的 `additional_data.risk_factors` 值恰好为 `["device_attribute"]` 时适用**（即服务商的“此设备看似可疑”信号，该信号通常在普通移动线路上触发）。任何其他风险因素、包含 `device_attribute` 但还混有其他因素的任何组合，或根本没有风险因素的拦截，无论设置如何都将直接拒绝。拦截原因（`repeated_attempts`、`suspicious` 或 `spam`）是一个独立字段，在 `additional_data.blocked_reason` 中返回。

与该设置无关的是，通过 [Lists API](https://docs.didit.me/zh/management-api/lists/overview.md) 创建的电话白名单中的号码绝不会因拦截发送而被自动拒绝：该步骤将进入**审核中**状态，警告带有 `log_type: "warning"`，且 `additional_data.phone_number_in_allowlist` 为 `true`。

## 验证尝试次数限制

电话验证功能对 OTP 尝试次数设置了硬性上限以防止滥用：

* **验证码输入尝试** — 默认为 **2** 次错误提交（`phone_max_check_attempts`），超过后该步骤将以 `Declined` 结束并产生 `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`。独立电话 API 允许每次验证进行 **3** 次验证码尝试。
* **发送尝试** — 默认共 **2** 次发送（`phone_max_retries`）：首次发送加上一次重新发送。后续的发送请求将直接结束该步骤并触发 `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`。
* **OTP 有效期** — 待处理的 OTP 有效期为**自首次发送起 5 分钟**；重试不会延长该时间窗口。

这两个上限均可在每个工作流节点上单独调整。独立于这些上限，投递服务商的反欺诈层可以直接拦截发送（原因包括 `repeated_attempts`、`suspicious` 或 `spam`）— 这将触发 `HIGH_RISK_PHONE_NUMBER`，而不是尝试次数警告。

## 生成的警告

| 标签 | `log_type` | 描述 |
| - | - | - |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `error`（始终） | 用户超过了 OTP 验证码输入或发送上限。自动拒绝。 |
| `HIGH_RISK_PHONE_NUMBER` | 遵循 `high_risk_phone_action`，或在加入白名单时为 `warning` | 投递服务商拦截了 OTP 发送。默认拒绝；将 `high_risk_phone_action` 设置为 `REVIEW` 可将仅因设备信号被拦截的情况转入审核中（参见[拦截发送](#被拦截的发送)）。在电话白名单上的号码也会转入审核中。`additional_data`：`{ blocked_reason, risk_factors, phone_number_in_allowlist? }`。 |
| `PHONE_NUMBER_IN_BLOCKLIST` | `error`（始终） | 该号码位于通过 [Lists API](https://docs.didit.me/zh/management-api/lists/overview.md) 创建的黑名单中，或与列入黑名单的会话匹配。自动拒绝。`additional_data`：`{ blocklisted_session_id, blocklisted_session_number, api_service }`（对于纯名单命中，全部为 `null`）。 |
| `PHONE_NUMBER_IN_ALLOWLIST` | `information` | 该号码与其他会话匹配，但位于通过 [Lists API](https://docs.didit.me/zh/management-api/lists/overview.md) 创建的白名单中，因此跳过重复电话操作。`additional_data`：`{ phone_number }`。 |
| `DISPOSABLE_NUMBER_DETECTED` | 遵循 `disposable_number_action` | 该号码属于常用于逃避可追溯性的临时/一次性服务商。 |
| `VOIP_NUMBER_DETECTED` | 遵循 `voip_number_action` | 该号码解析为 `voip`、`isp` 或 `vpn` 线路，而非标准移动或固定线路。 |
| `DUPLICATED_PHONE_NUMBER` | 遵循 `duplicated_phone_number_action` | 该号码与属于不同终端用户（按 `vendor_data` 分组）的另一个会话（处于任意状态）匹配。`additional_data`：`{ duplicated_session_id, duplicated_session_number, api_service }`。 |

## 跨会话匹配

当在其他会话或您的黑名单中检测到某个号码时，这些命中结果还会显示在 `phone_verifications[].matches[]` 下（最多 5 条记录）。每条匹配包含 `session_id`、`session_number`、`vendor_data`、`verification_date`、`phone_number`、`status`、`is_blocklisted`、`api_service`，以及 `source` 为 `session`（具有相同号码的另一个会话，任意状态）或 `list_entry`（预置在数组开头的虚拟黑名单命中记录）。如果当前号码在您的电话白名单中，Didit 会保留匹配证据，但会发出 `PHONE_NUMBER_IN_ALLOWLIST` 而不是执行重复电话操作。有关完整匹配架构，请参阅[电话验证报告](https://docs.didit.me/zh/core-technology/phone-verification/report-phone-verification.md#跨会话匹配)。

## 示例

VoIP 号码上的拦截发送（`HIGH_RISK_PHONE_NUMBER`），其中 `voip_number_action` 配置为 `REVIEW`：

```json theme={null}
{
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "HIGH_RISK_PHONE_NUMBER",
      "additional_data": { "blocked_reason": "suspicious" },
      "log_type": "error",
      "short_description": "High risk phone number",
      "long_description": "The system detected that the phone number is a high risk phone number, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ]
}
```

## 警告类型

每个风险都会根据您应用的配置分配一个严重程度级别。严重程度分为三类：

## 相关内容

* [电话验证概述](https://docs.didit.me/zh/core-technology/phone-verification/overview.md) — 功能行为、定价、支持的渠道。
* [电话验证报告](https://docs.didit.me/zh/core-technology/phone-verification/report-phone-verification.md) — 包括 `lifecycle[]` 和 `matches[]` 在内的完整响应结构。
* [数据模型 — 电话验证](https://docs.didit.me/zh/reference/data-models.md#电话验证) — 逐字段的标准架构规范。
* [Management API — 名单](https://docs.didit.me/zh/management-api/lists/overview.md) — 管理供 `PHONE_NUMBER_IN_BLOCKLIST` 使用的电话黑名单。


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