错误代码
本页是错误处理的唯一权威来源。SDK 专属错误代码记录在各 SDK 的错误处理页面；本页涵盖 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 | 资源曾存在，但已按保留策略删除（文件获取端点），或流程存在但以错误状态结束——参见获取流程。 | 文件获取端点；API 获取流程。 |
429 Too Many Requests | 您已触发频率限制。请使用指数退避策略重试。 | 所有合约。 |
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 |
请参阅认证 > 常见错误获取完整的故障排查清单。
能力级别结果（带有否定结果的 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.result.status | not_verified | 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 的专属错误处理页面：
这些页面涵盖设备端错误（摄像头权限被拒、采集超时、设备网络不可达），与本页记录的 API 端错误相互独立。