> ## 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 API 错误码：状态码、响应体与修复方法

> Didit 全部 API 错误说明：HTTP 状态码、响应体结构、稳定错误码，以及哪些失败可安全重试。涵盖 401、403、409、429 和 5xx。

Didit API 在请求失败时会返回 HTTP 状态码，几乎所有情况下还会返回 JSON 响应体。
本页列出每个状态码的含义、响应体的结构、可以据此分支处理的 `code` 值，以及哪些失败可以安全重试。
请优先依据状态码判断；存在 `code` 时，再依据它判断，因为消息文本可能会变化。

## 状态码

| 状态码 | 含义 | 处理方法 | 是否重试？ |
| - | - | - | - |
| `400` | 请求无效：某个字段未通过校验，或无法读取图片或证件 | 修正响应体中指出的内容 | 修正后重试 |
| `401` | 您发送的密钥错误、格式不正确、已被撤销或已过期 | 检查 `DIDIT_API_KEY`，或创建新密钥 | 修正后重试 |
| `402` | 无法为本次检查付费，因此检查未执行 | 为余额充值 | 充值后重试 |
| `403` | 未发送密钥、密钥无权访问该资源或执行该操作、请求来自密钥 IP 列表之外，或余额不足以支付本次调用 | 阅读响应体，然后参阅 [API 密钥错误](#api-密钥错误) 和 [额度不足](#额度不足) | 修正后重试 |
| `404` | 资源不存在，或会话超出了密钥的工作流或状态范围 | 检查 ID 以及密钥的限制 | 否 |
| `409` | 请求与当前状态冲突，例如重复使用了 `Idempotency-Key`，或某个步骤已经执行过 | 读取 `code` 并重新加载状态 | 取决于 `code` |
| `410` | 资源已过期，例如会话或邀请 | 创建新的资源 | 否 |
| `415` | 请求体不是 JSON | 发送 `Content-Type: application/json` | 修正后重试 |
| `422` | 地址对应多条区块链，因此未进行筛查，也未计费 | 将 `blockchain` 设置为 `candidate_chains` 中的一个值后重新发送 | 修正后重试 |
| `429` | 已达到速率限制或配额上限 | 等待 `Retry-After` 指定的时间；参阅 [速率限制](https://docs.didit.me/zh/integration/rate-limiting.md) | 是，等待后重试 |
| `500` | Didit 一侧出现未预期的错误 | 使用退避策略重试；如果问题持续，请联系支持团队 | 参阅 [重试](#重试与幂等性) |
| `502` | Didit 所依赖的服务返回了错误 | 读取 `code` | 参阅 [重试](#重试与幂等性) |
| `503` | Didit 所依赖的服务暂时不可用 | 读取 `code` 并稍后重试 | 参阅 [重试](#重试与幂等性) |

## 错误响应体

错误响应体的结构并不统一，因此请进行防御式解析。具体结构取决于 endpoint 系列：

| 结构 | 出现位置 | 示例 |
| - | - | - |
| `detail` | 大多数错误，包括身份验证、未找到和速率限制 | `{"detail": "You do not have permission to perform this action."}` |
| `detail` 和 `code` | 带有稳定错误码的错误 | `{"detail": "This application was deleted.", "code": "application_deleted"}` |
| 字段错误 | 输入校验 | `{"workflow_id": ["This field is required."]}` |
| `non_field_errors` | 跨字段校验 | `{"non_field_errors": ["..."]}` |
| JSON 数组 | 部分校验错误，例如模拟调用 | `["Scenario can only be armed before the verification starts."]` |
| `error` | 大多数独立 API | `{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| `error` 和 `code` | 独立 API 中的图片错误 | `{"error": "...", "code": "invalid_image"}` |
| 以错误码形式出现的 `error`，并附带 `detail` | 数字身份钱包验证 | `{"error": "insufficient_credits", "detail": "..."}` |

`500` 可能完全没有 JSON 响应体，因此请处理无法解析的响应体。

```javascript theme={null}
const raw = await response.text();
let body = {};
try {
  body = JSON.parse(raw);
} catch {
  // A 5xx response may not be JSON: rely on response.status.
}
const code = body.code ?? null;
const message = body.detail ?? body.error ?? (Array.isArray(body) ? body[0] : raw);
```

## API 密钥错误

| 发送的内容 | 状态码 | `detail` |
| - | - | - |
| 没有 `x-api-key` 请求头 | `403` | `You do not have permission to perform this action.` |
| 错误、格式不正确或已被撤销的密钥 | `401` | `Authentication credentials were not provided or are invalid.` |
| 已过期的密钥 | `401` | `This API key has expired.` |
| 从其 IP 列表之外使用的密钥 | `403` | `This API key can't be used from this IP address.` |
| 作用域受限、无权访问该资源或操作的密钥 | `403` | `This API key has no access to this endpoint.` |
| 仅限部分工作流或状态、却用于其无权使用的 endpoint 的密钥 | `403` | `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.` |
| 仅限部分工作流或状态、用于超出这些限制的会话的密钥 | `404` | `Session not found.` |
| 所属应用刚被删除的密钥 | `403` | `This application was deleted.`，并附带 `"code": "application_deleted"` |

应用被删除后的几分钟内，API 会返回 `application_deleted`；之后则会像对待任何错误密钥一样拒绝该密钥。
请不要重试：应用及其密钥均已删除。

有关密钥及其限制的工作原理，请参阅 [API 身份验证](https://docs.didit.me/zh/getting-started/api-authentication.md) 和 [API 密钥](https://docs.didit.me/zh/console/api-keys.md)。

## 额度不足

各 API 系列报告余额不足的方式各不相同：

| 调用 | 状态码 | 响应体 |
| - | - | - |
| `POST /v3/session/` | `400` | `{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| 大多数独立 API | `403` | `{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| `POST /v3/bank/account-check/` | `402` | `{"detail": "...", "code": "insufficient_credits"}` |
| 数字身份钱包验证 | `403` | `{"error": "insufficient_credits", "detail": "..."}` |
| 交易、Travel Rule 和地址校验 | `403` | `{"detail": "...", "code": "insufficient_credits"}` |

签订合同的客户在其所属组织的付费服务被暂停期间，创建会话会返回 `403`，并附带 `"code": "contract_billing_suspended"`。
[沙盒应用](https://docs.didit.me/zh/integration/sandbox-testing.md) 从不计费，因此不进行这些检查。

## 错误代码

这些 `code` 值是稳定的，因此您可以据此进行分支判断。多数情况下，它与 `detail` 并列返回；在数字身份钱包验证中，错误代码是 `error` 的值。

### 访问与计费

| 代码 | 状态 | 含义 |
| - | - | - |
| `insufficient_credits` | `402`, `403` | 余额不足以支付此次调用 |
| `contract_billing_suspended` | `403` | 此组织的付费服务已暂停 |
| `contract_rate_missing` | `402`, `403` | 合同中没有此项检查的费率 |
| `application_deleted` | `403` | 密钥所属的应用已被删除 |
| `organization_deleted` | `403` | 密钥所属的组织已被删除 |
| `event_monitoring_disabled` | `403` | 该应用未开启事件接收 |
| `networks_not_entitled` | `403` | 此组织未启用欺诈网络 |

### 请求与幂等性

| 代码 | 状态 | 含义 |
| - | - | - |
| `invalid_image` | `400` | 无法使用该图片 |
| `return_url_invalid` | `400` | 不允许该返回 URL |
| `idempotency_key_invalid` | `400` | `Idempotency-Key` 超过 255 个字符 |
| `idempotency_key_reused` | `409` | 该密钥已用于不同的请求体 |
| `idempotency_key_in_progress` | `409` | 使用此密钥的首个请求仍在运行；请等待 `Retry-After` |
| `verification_in_progress` | `409` | 用户正在完成此验证，因此无法取消；请等待 `Retry-After` |
| `feature_override_not_pending` | `409` | 该覆盖设置已生效或已取消 |

### 银行、电话与风险检查

| 代码 | 状态 | 含义 |
| - | - | - |
| `invalid_account_input` | `400` | 账户信息无效 |
| `country_not_covered` | `404` | 该检查不覆盖此国家/地区或此类账户 |
| `bank_not_covered` | `404` | 该检查无法覆盖此银行 |
| `bank_verification_not_available` | `404` | 银行验证不可用 |
| `account_check_unavailable` | `503` | 检查暂时不可用，该请求未被计费 |
| `phone_provider_unavailable` | `502` | 电话验证暂时不可用；不产生费用，也不消耗尝试次数 |
| `risk_lookup_unavailable` | `502` | 风险查询暂时不可用，该请求未被计费 |

### 企业验证（KYB）

| 代码 | 状态 | 含义 |
| - | - | - |
| `kyb_registry_provider_unavailable` | `502` | 公司登记暂时不可用 |
| `kyb_registry_country_unsupported` | `400` | 公司登记搜索不覆盖此国家/地区 |
| `kyb_registry_search_limit_reached` | `429` | 应用已达到每小时 600 次付费搜索的上限 |
| `kyb_session_not_writable` | `409` | 会话已结束 |
| `kyb_step_mismatch` | `409` | 会话处于其他步骤；`next_step` 指明该步骤 |
| `kyb_no_party_drafts` | `409` | 没有可提交的参与方草稿 |
| `kyb_parties_already_submitted` | `409` | 参与方已提交 |
| `kyb_party_kyc_session_not_deleted` | `409` | 该参与方的验证仍有效，因此无法重新生成 |

### 数字身份钱包

| 代码 | 状态 | 含义 |
| - | - | - |
| `wallet_unavailable` | `403` | 您的应用无法使用此钱包 |
| `wallet_provider_unavailable` | `502` | 钱包无法启动，未创建任何内容 |
| `wallet_not_configured` | `503` | 当前环境无法访问该钱包 |

### 报告与案件

| 代码 | 状态 | 含义 |
| - | - | - |
| `report_deletion_pending` | `409` | 报告正在删除中；请重复执行删除操作，以彻底清除其文件 |
| `report_storage_unavailable` | `503` | 无法清除报告的文件；请重复执行删除操作 |
| `wallet_address_deletion_incomplete` | `503` | 某个已存储的文件无法删除，因此删除已中止；请重试 |
| `case_request_not_waiting` | `409` | 该请求已不再等待客户处理，因此无需发送提醒 |
| `case_request_reminder_too_soon` | `429` | 最近已发送过提醒；`retry_at` 指明可以发送下一次提醒的时间 |

### 电子签名

| 代码 | 状态 | 含义 |
| - | - | - |
| `signature_not_found` | `404` | 签名不存在 |
| `signature_field_not_found` | `404` | 签名字段不存在 |
| `signature_not_signed` | `404`, `409` | 证件尚未签名 |

创建会话时，下列证件问题会以出错字段的值返回，状态码为 `400`，例如 `{"sign": "signature_document_changed"}`：

| 值 | 含义 |
| - | - |
| `signature_document_changed` | 证件与首次发送的证件不同 |
| `signature_document_not_supported` | 不支持该证件格式 |
| `signature_document_conversion_failed` | 证件无法转换 |
| `field_anchor_not_found` | 在证件中未找到字段的文本锚点 |
| `field_value_missing` | 字段缺少值 |

### Webhook

| 代码 | 状态 | 含义 |
| - | - | - |
| `webhook_url_missing` | `400` | 该投递没有记录的 URL，因此不会发送任何内容 |
| `invalid_webhook_payload` | `400` | Webhook 数据格式无效 |
| `webhook_resend_error` | `400` | 已存储的投递无法重新签名，或该次尝试无法完成 |

## 重试与幂等性

有些失败可以安全地重复，有些则不行：

* **`429`：**等待 `Retry-After` 请求头，然后重试。
* **`502` 和 `503`：**当端点的参考文档说明未产生计费时（电话、邮箱、银行和风险检查均是如此），使用退避策略重试。
* **`POST /v3/database-validation/` 返回 `502`：**先逐条读取每个 `validation_errors` 条目，因为仅此状态码并不代表临时故障。
* **删除操作返回 `503`：**重复发送相同请求，直到返回 `200`。
* **其他 `4xx`：**先修正请求，因为同一请求会以相同方式再次失败。

`POST /v3/aml/` 和数字身份钱包验证接受长度不超过 255 个字符的 `Idempotency-Key` 请求头。使用相同密钥和相同请求体重复请求时，会重放已存储的响应，因此操作和扣费只执行一次。使用相同密钥但请求体不同，会返回 `409`；第一个请求仍在处理时，钱包端点会返回带有 `Retry-After` 的 `409`。

`POST /v3/session/` 没有幂等性密钥，因此如果创建会话时超时，请先按 `vendor_data` 列出您的会话，再创建新的会话。

## 相关内容

* [速率限制](https://docs.didit.me/zh/integration/rate-limiting.md)：限制、请求头和 `429` 响应体。
* [API 认证](https://docs.didit.me/zh/getting-started/api-authentication.md)：说明如何发送您的密钥。
* [沙盒测试](https://docs.didit.me/zh/integration/sandbox-testing.md)：在不使用真实数据或不产生计费的情况下复现结果。
* [Webhook](https://docs.didit.me/zh/integration/webhooks.md)：投递、重试和顺序。


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