Didit API 错误码：状态码、响应体与修复方法

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

状态码

状态码	含义	处理方法	是否重试？
`400`	请求无效：某个字段未通过校验，或无法读取图片或证件	修正响应体中指出的内容	修正后重试
`401`	您发送的密钥错误、格式不正确、已被撤销或已过期	检查 `DIDIT_API_KEY`，或创建新密钥	修正后重试
`402`	无法为本次检查付费，因此检查未执行	为余额充值	充值后重试
`403`	未发送密钥、密钥无权访问该资源或执行该操作、请求来自密钥 IP 列表之外，或余额不足以支付本次调用	阅读响应体，然后参阅 API 密钥错误和额度不足	修正后重试
`404`	资源不存在，或会话超出了密钥的工作流或状态范围	检查 ID 以及密钥的限制	否
`409`	请求与当前状态冲突，例如重复使用了 `Idempotency-Key`，或某个步骤已经执行过	读取 `code` 并重新加载状态	取决于 `code`
`410`	资源已过期，例如会话或邀请	创建新的资源	否
`415`	请求体不是 JSON	发送 `Content-Type: application/json`	修正后重试
`422`	地址对应多条区块链，因此未进行筛查，也未计费	将 `blockchain` 设置为 `candidate_chains` 中的一个值后重新发送	修正后重试
`429`	已达到速率限制或配额上限	等待 `Retry-After` 指定的时间；参阅速率限制	是，等待后重试
`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 响应体，因此请处理无法解析的响应体。

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 身份验证和 API 密钥。

额度不足

各 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"。沙盒应用从不计费，因此不进行这些检查。

错误代码

这些 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 列出您的会话，再创建新的会话。

指南

身份认证

模型上下文协议（MCP）

Web SDK

原生 SDK

服务端 SDK

集成

Didit API 错误码：状态码、响应体与修复方法

状态码

错误响应体

API 密钥错误

额度不足

错误代码

访问与计费

请求与幂等性

银行、电话与风险检查

企业验证（KYB）

数字身份钱包

报告与案件

电子签名

Webhook

重试与幂等性

相关内容

​状态码

​错误响应体

​API 密钥错误

​额度不足

​错误代码

​访问与计费

​请求与幂等性

​银行、电话与风险检查

​企业验证（KYB）

​数字身份钱包

​报告与案件

​电子签名

​Webhook

​重试与幂等性

​相关内容

状态码

错误响应体

API 密钥错误

额度不足

错误代码

访问与计费

请求与幂等性

银行、电话与风险检查

企业验证（KYB）

数字身份钱包

报告与案件

电子签名

Webhook

重试与幂等性

相关内容