乾策立方开放平台文档

错误码与排查

HTTP 状态	statusCode	说明
400	400 / 101	请求参数错误，例如标题为空、附件为空、virtualId 无效等。时间参数必须带显式时区（`Z` 或 `±HH:MM`），不带时区的裸值一律拒绝，错误信息会指明具体字段。
400	102	必填标识缺失，或目标资源不存在、不可写。同一码覆盖多种对象（企业上下文、资源编号、便签/任务/标签 Id、被申请人等），也可能是不属于当前企业的资源或无访问权限；具体原因以 `msg` 为准，不要按本码推断是哪一类资源缺失。
400	103	取值越界、形态不合法或动作名不支持。典型：缺少操作人 Id、修改值 `value` 为空、检查项取值不符合消费端契约、单次资源编号超过 50 个、标签动作不在 `add/update/delete` 之内、操作人不是该任务的相关人员。
400	104	操作人不存在（已离职、不在当前企业或员工上下文失效），或目标记录不存在（如贡献申请记录）。
400	105	请求无法映射到允许的取值。典型：附件请求未携带文件；`fieldType` 不在支持的修改字段类型内，`msg` 会列出支持的取值清单。
400	106	一次只能上传一个附件；请拆成逐次请求。
401	40101	缺少认证请求头。
401	40102	API Key 无效。
401	40103	时间戳格式错误。
401	40104	请求已过期。
401	40105	签名校验失败。
401	40106	Nonce 重复，或请求被重复使用。
401	401	认证上下文缺失的兜底码：请求到达业务层时没能建立企业/操作人上下文（如缺少凭据头、内网鉴权未通过被网关透传）。它不带 `401xx` 具体子码，排查时先看 `msg`；正常带 Key 签名调用不应命中本码。
403	40301	API Key 已停用。
403	40302	API Key 已过期。
403	40303	IP 不在白名单中。
403	40304	操作人不属于当前企业，或当前员工上下文无效。
403	40305	企业集成通道闸门拒绝：企业未购买「开放平台」服务套餐模块，或源站服务状态校验未通过（含校验接口暂不可用时的按拒绝处理）。后者属临时状态，可稍后重试；持续出现请联系平台确认企业套餐状态。
403	403	权限不足，或缺少 `X-Employee-Virtual-Id`，或当前 API Key 未授权指定能力。
404	404	员工、任务、绑定关系等资源不存在。
400	161	附件直传通道未开放：当前成员的上传上限为 0。`attachment_upload_begin` 阶段即拒绝，不产生票据。
400	162	成员当日上传字节额度不足，申报字节超过剩余额度。请改小文件或按企业口径调整成员额度。
400	163	文件类型不允许。`MCP` base64 代传与 REST 代传的类型拒绝共用本码，扩展名或内容类型不在企业允许清单内。
400	164	直传票据不存在或不属于当前调用方；请重新发起 `attachment_upload_begin` 并使用其返回的票据 Id。
400	165	票据已结算或正被其他请求验收（同一票据重复 `complete`/`abort`）。首次调用结果已确定，不要自动重试。
400	166	直传票据已过期（票据有效期见 `begin` 返回的过期时间），请重新签发票据。
400	167	直传对象缺失或实际字节与申报不符：未完成对象上传、上传后又被删除，或真实大小与 `begin` 申报值不一致。
400	168	定稿资源不可匿名读取，无法继续代传或换发地址。
400	169	运行前置条件不满足（依赖的通道、配置或资源状态未就绪）。`msg` 给出具体前置项；本码属服务端状态，重试仍失败时请带请求时间与接口路径反馈。
413	413	附件请求体或文件大小超过系统限制（含 multipart 请求体超限、实际字节超过申报上限）。HTTP 状态与 `statusCode` 同为 413。
429	429	请求频率超限：按调用方与操作人维度的每分钟配额已用完。`msg` 给出上限值，请退避后重试；HTTP 状态与 `statusCode` 同为 429。
502	2100	企业套餐已到期，30 天只读宽限期内拒绝写操作（查询类接口不受影响）。未认证企业会附带“完成认证可获得体验天数”提示。
502	2101	企业套餐到期超过 30 天，开放平台全部接口已停用。
502	2102	企业已购套餐不包含该接口所属功能模块（任务/便签/项目/目标/贡献/福利/汇报/成就/奖章/网盘）。
400	109	任务进展内容超过 1000 字上限（与工作台和移动端提交进展输入框同口径）。
400	110	任务进展内容含 HTML 标签。进展是纯文本字段，服务端不做清洗也不截断，去掉正文中的标签后重新提交即可；任务正文才使用 HTML 富文本。
400	111	任务进展不属于当前操作人。修改进展要求「当天」且「本人提交」两个条件同时成立，与 `108`（跨天）分属两种拒绝原因；该口径由源站统一执行，工作台、移动端与开放平台四入口一致。
400	113	任务贡献点低于企业策略下限。企业配置了最低贡献点且大于 0 时，创建或修改任务必须传不低于该值的 `score`；未传按 0 处理即命中本错误码，任务不会创建。下限取值见创建初始化数据返回的 `sendMinScore`。
400	115	提交过于频繁，被源站防抖拒绝：同一企业的同一操作人在 5 秒内重复创建自动化任务时命中本错误码，上一条请求不受影响。请稍后重试，不要按参数错误排查。
400	138	任务正文无有效内容：正文非空却被服务端判为不含文字、图片与链接中的任意一项（常见于把纯空白、仅结构标签或经过额外一层转义的内容当作正文）。创建任务与 `task_update` 修改 `content` 均命中本码，任务不会被创建、原正文也不会被清空；确需空正文时请不传 `content`，不要重试同一载荷。
502	502 及 2100-2102	开放平台网关调用下游内部服务失败，或下游返回结构异常；2100-2102 为套餐与到期拒绝，按 502 返回但携带源站原始提示。源站内网端点的业务结果码统一经出口映射器翻译成小于 500 的公开码（如 101、113、115），因此"请求被拒绝"不会再被说成"下游服务处理失败"；未登记的共享层高位码一律折算为 500，原始码会记入源站日志，反馈时请附请求时间与接口路径以便定位。
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 返回结果。