全局错误码字典 (Error Codes)

STATUS CODES 全局统一异常与排查标准

开放平台在处理请求发生异常时，会同时返回符合语义的 HTTP 状态码（如 400、401、403、404、409、429、500）以及统一结构的 JSON 错误响应体。调用方可根据业务错误码 code 精准定位失败原因。

错误响应数据结构 (Error Response)

当 API 请求处理失败时，服务端返回的 HTTP 响应体结构如下：

JSON 错误报文示例

{
  "code": 40101,
  "message": "签名校验失败",
  "request_id": "req_68dfb7829a10ef4"
}

字段名	类型	说明
code	integer	五位十进制业务错误码（通常前 3 位与 HTTP 状态对应），`0` 代表成功，非 0 代表对应错误。
message	string	人类可读的错误原因描述文本，可用于前端提示或调试日志记录。
request_id	string	全链路分布式请求跟踪唯一 ID。如遇非预期服务端错误，请务必提供该值给技术支持排查。

错误码完整对照表 (Error Codes Dictionary)

HTTP 状态	错误码 (code)	错误标识 (Constant)	产生原因与排查指引
400	40001	BAD_REQUEST	请求体参数校验失败：缺少必填字段（如 `source.template_id`、`recipients` 为空数组）、数据类型不符合约束，或者传入了当前版本不支持的字段。请对照接口文档核对 JSON 请求格式。
401	40101	AUTHENTICATION_FAILED	认证失败或签名错误：Access Key 无效、已禁用或撤销；或者待签名字符串与 Secret Key 计算所得签名与服务端不匹配。请参阅公共请求头文档自检测试向量。
401	40103	TIMESTAMP_OUT_OF_RANGE	请求时间戳超出允许范围：标头 `X-Api-Timestamp` 与服务端系统时钟偏差大于 ±300 秒（5分钟）。请检查并校准调用端宿主机服务器的 NTP 时间。
401	40104	NONCE_REPLAYED	随机数重放拦截：标头 `X-Api-Nonce` 在 300 秒有效期内被重复使用。为防止网络抓包重放攻击，每次 HTTP 请求必须生成全新的密码学随机串。
403	40301	FORBIDDEN	业务操作无权限：当前 API 凭证绑定的账号已被移除出目标企业，或已被限制发起文档业务权限。
403	40302	IP_NOT_ALLOWED	IP 白名单拦截：调用方客户端出口公网 IP 不在目标企业在开放平台管理后台配置的白名单列表中。请登录控制台添加服务器出口 IP。
403	40303	ENTITLEMENT_REQUIRED	产品权益未生效：目标企业尚未开通开放平台 API 电子签署产品权益（产品标识 `60003`）。请联系企业管理员开通相应功能权益。
404	40401	NOT_FOUND	目标资源不存在：指定的模板 ID、文档 ID 不存在，或该资源属于其他企业/其他成员，当前凭证无权跨租户访问。
409	40901	RESOURCE_CONFLICT	资源状态冲突：目标模板处于草稿或停用状态无法发起，或目标文档处于当前动作不支持的阶段（例如尚未签署完毕无法下载已签文件）。
409	40902	IDEMPOTENCY_KEY_REUSED	幂等键冲突：相同的 `Idempotency-Key` 被重复使用，但传入了不同的请求 Body 参数。幂等重试必须保证请求体参数内容完全一致。
409	40903	PROCESSING	任务仍在处理中：该 `Idempotency-Key` 正在服务端流水线执行中。响应头中会附带 `Retry-After: 5`，请等待指定秒数后按原参数重试。
413	41301	QUOTA_EXHAUSTED	合同签署额度已耗尽：当前企业的套餐签署次数额度已不足，请登录管理后台订购或充值额度包。
429	42901	RATE_LIMITED	请求频率受限：当前凭证或企业调用频率触发了平台的频控限流策略。建议在客户端加入请求队列与指数退避重试机制。
500	50001	INTERNAL_ERROR	服务端内部错误：文件渲染或签署流水线发生未预期的内部错误。请记录返回的 `request_id` 提交技术支持反馈。
503	50301	DEPENDENCY_UNAVAILABLE	基础依赖服务暂时不可用：底层证书机构、短信通道或对象存储出现短暂抖动，通常稍后重试即可恢复。

错误排查与重试建议 (Best Practices)

幂等任务处理中 (40903) 的重试策略

当发起创建类写操作请求遇到网络超时、或服务端返回 40903 时，表示当前请求正在后台加锁流转。请读取 HTTP 响应标头 Retry-After（一般为 5 秒），休眠对应时长后使用完全相同的请求体与相同的 Idempotency-Key 重试，完成后将直接返回首次处理成功的结果。

频控限流 (42901) 与服务抖动退避算法

遇到 42901 或 50301 错误时，建议客户端采用带抖动的指数退避（Exponential Backoff with Jitter）算法进行自动重试，避免瞬时大量并发重试引起服务雪崩：

重试等待时间 = min(最大等待时间, 初始等待时间 × 2^(重试次数)) + 随机抖动毫秒