错误码与排查
| HTTP 状态 | statusCode | 说明 |
|---|---|---|
| 400 | 400 / 101 | 请求参数错误，例如标题为空、附件为空、virtualId 无效等。 |
| 401 | 40101 | 缺少认证请求头。 |
| 401 | 40102 | API Key 无效。 |
| 401 | 40103 | 时间戳格式错误。 |
| 401 | 40104 | 请求已过期。 |
| 401 | 40105 | 签名校验失败。 |
| 401 | 40106 | Nonce 重复，或请求被重复使用。 |
| 403 | 40301 | API Key 已停用。 |
| 403 | 40302 | API Key 已过期。 |
| 403 | 40303 | IP 不在白名单中。 |
| 403 | 40304 | 操作人不属于当前企业，或当前员工上下文无效。 |
| 403 | 403 | 权限不足，或缺少 X-Employee-Virtual-Id，或当前 API Key 未授权指定能力。 |
| 404 | 404 | 员工、任务、绑定关系等资源不存在。 |
| 502 | 502 及其他大于 100 的状态码 | 开放平台网关调用下游内部服务失败，或下游返回结构异常。 |
| 500 | 500 | 系统异常。 |
状态码约定：
HTTP 状态码 用于表示错误大类（如 401 认证失败、403 授权失败），statusCode 用于表示更细粒度、可供程序稳定判断的机器错误码；两者不要求一一对应。
日志说明：开放平台请求日志会记录请求体和响应体，日志中的手机号、姓名、各种业务 Id、virtualId、第三方用户标识等敏感字段都会做脱敏处理。GET 请求会把查询串按
[query]?... 形式写入 RequestBody，并按字段名统一脱敏。
常见排查项
- 确认 API Key 已启用、未过期，且命中白名单。
- 确认签名原文中的路径、QueryString、Body 与真实请求完全一致。
- 确认每次请求都重新生成
X-Timestamp、X-Nonce、X-Signature，不要在重试或并发请求中复用旧请求头。 - 确认需要当前员工身份的接口都传了
X-Employee-Virtual-Id。 - 确认被引用的员工
virtualId来自当前 API Key 下的/employees返回结果。