--- title: 错误代码 description: 涵盖 Web & SDK、API 和 Magic Link 合约的 HTTP 及平台错误代码综合目录。 canonical: https://developer.unico.io/zh-CN/dual-api/developers/api-reference/error-codes locale: zh-CN generated_by: markdown-export --- - [/zh-CN/](/zh-CN/) - [API 参考](/zh-CN/dual-api/developers/api-reference/) - 错误代码 **本页内容# 错误代码 本页是错误处理的唯一权威来源。SDK 专属错误代码记录在各 SDK 的[错误处理](/zh-CN/dual-api/developers/sdks-and-tools/web/web-sdk/error-handling)页面；本页涵盖 API 合约层面的错误。 ### HTTP 状态码​ 代码含义适用范围`200 OK`请求成功。所有合约。`201 Created`资源已创建（少见；大多数创建操作返回 `200`）。API 合约。`400 Bad Request`请求体格式错误或缺少必填字段。响应体会指明问题字段。所有合约。`401 Unauthorized`认证缺失、已过期或无效。所有合约。`403 Forbidden`认证有效，但租户未开通所请求的资源（例如，调用不在您 `APIKEY` 中的能力）。Web & SDK、API。`404 Not Found`资源不存在或不属于已认证的租户。所有合约。`409 Conflict`资源存在，但当前状态不符合此操作的要求（例如，从仍在处理中的流程获取文件）。Web & SDK、API。`410 Gone`资源曾存在，但已按保留策略删除（文件获取端点），或流程存在但以错误状态结束——参见[获取流程](/zh-CN/dual-api/developers/api-reference/api/get-process)。文件获取端点；API 获取流程。`429 Too Many Requests`您已触发[频率限制](/zh-CN/dual-api/developers/api-reference/rate-limits)。请使用指数退避策略重试。所有合约。`5xx`平台错误。请使用退避策略重试；如持续出现，请携带响应体和时间戳联系支持团队。所有合约。 ### 认证错误（`401`）​ 原因现象私钥错误（断言使用了错误的密钥签名）`401`，`Authentication failed (1.2.21)``aud` 与环境 URL 不匹配`401``exp` 声明已过期`401`，`Authentication failed`不支持的算法（请使用 `RS256`）`401`沙箱与生产环境凭证混用`401`，即使凭证看起来正确缺少 `APIKEY` 请求头（仅 API 合约）`401``x-api-key` 无效（仅 Magic Link）`401` 请参阅[认证 > 常见错误](/zh-CN/dual-api/developers/api-reference/authentication#error-codes)获取完整的故障排查清单。 ### 能力级别结果（带有否定结果的 `200`）​ `200 OK` **并不**意味着用户通过了验证——它只表示平台完成了处理。面向用户的决策结果在响应体中，而非 HTTP 状态码： 字段否定值出现位置`process.result``PROCESS_RESULT_FAILED`Web & SDK`process.authenticationInfo.livenessResult``NO`Web & SDK`liveness``2`API`unicoId.result``no`API`data.response.unico.result``NOT_APPROVED`Magic Link ### 重试策略​ 状态是否重试？方式`5xx`是指数退避（1s、2s、4s、8s……），最多重试 5 次。`429`是若响应包含 `Retry-After` 请求头则遵从；否则使用指数退避。`4xx`（其他）否请求本身有误，请修正输入后再试。`401`有条件刷新一次访问令牌后重试。若新请求仍返回 `401`，则问题属于结构性问题——不要继续重试。 幂等性IDCloud 平台目前在创建端点上未提供幂等键机制。对 `POST /client/v1/process` 或 `POST /processes/v1` 进行重试时需谨慎——`5xx` 上的网络错误实际上可能已在服务器端成功，重试将创建重复流程。如有疑问，请在重试前根据您的内部关联 ID 查询最近的流程。 ### SDK 错误的位置​ Web SDK、Android SDK、iOS SDK 和 Flutter SDK 的错误目录分别记录在各 SDK 的专属**错误处理**页面： [Web SDK > 错误处理](/zh-CN/dual-api/developers/sdks-and-tools/web/web-sdk/error-handling) [Android SDK > 错误处理](/zh-CN/developers/sdks-and-tools/android/error-handling) [iOS SDK > 错误处理](/zh-CN/developers/sdks-and-tools/ios/error-handling) [Flutter SDK > 错误处理](/zh-CN/developers/sdks-and-tools/flutter/error-handling) 这些页面涵盖设备端错误（摄像头权限被拒、采集超时、设备网络不可达），与本页记录的 API 端错误相互独立。最后更新 于 2026年10月8日**