错误与状态规范

1. HTTP 返回的含义

HTTP 状态	含义	业务项目处理
`200`	相同幂等请求已存在，返回原记录	按成功受理处理，不再次生成新幂等键
`202`	新通知已进入队列	保存 `id`，不要当作已经送达
`401`	项目、时间戳或签名认证失败	停止重试，检查配置、时钟和签名实现
`404`	查询的投递记录不存在或不属于当前项目	检查投递 ID，不能跨项目查询
`409`	nonce 重放或幂等内容冲突	nonce 重放可用新 nonce 重发；幂等冲突必须修正业务逻辑
`422`	消息字段、标题、长度或跳转地址不合法	修正请求内容后再提交
`500`	通知中心内部异常	保留原幂等键，短暂退避后有限重试并告警

2. 投递状态

状态	含义	是否终态
`pending`	已受理，等待发送	否
`sending`	工作进程正在投递	否
`retrying`	明确未受理，等待通知中心自动重试	否
`sent`	钉钉已接受发送请求，等待读取结果	否
`unread`	已投递但收件人尚未阅读	否
`read`	收件人已经阅读	是
`failed`	已确定失败或投递结果不确定且为避免重复而隔离	是

业务项目一般不需要自己重发 pending / sending / retrying / sent / unread 状态。通知中心会处理明确可重试的失败并查询已读状态。

3. 标准边界

业务项目必须按统一请求契约提交 recipientUserId 或 recipientAlias、标题、正文和幂等键；actionUrl 可空且非空时原样透传。通知中心不识别采购流程、供应商账号、邮箱等项目私有字段。
收件人解析和业务人员配置由接入方负责。姓名、邮箱、外部联系人 ID 和自行拼接的标识不能代替钉钉内部员工 userId。
接入方以 HTTP 状态和投递 status 作为自动控制流程依据；lastErrorCode 用于诊断和人工处置，不得根据未知错误码自行重发。
本规范公布的统一 lastErrorCode 语义稳定；尚未归一化的钉钉厂商错误码或附在 lastErrorMessage 中的厂商信息只供通知中心维护人排查，不构成对接契约。

4. 常见错误码

错误码	原因	处理方式
`AUTH_REQUIRED`	项目不存在或签名请求头缺失	检查项目配置和请求头
`TIMESTAMP_EXPIRED`	客户端与服务器时间相差超过五分钟	校准系统时间后使用新 nonce 重发
`NONCE_INVALID`	nonce 格式不符合要求	使用 16～100 位随机 URL 安全字符串
`SIGNATURE_INVALID`	签名路径、正文或密钥不一致	使用实际 raw body 和内部 API path 重新计算
`NONCE_REPLAYED`	nonce 已经使用过	生成新 nonce，业务幂等键保持不变
`RECIPIENT_SELECTOR_CONFLICT`	同时提交了 `recipientUserId` 和 `recipientAlias`	两种收件人方式只保留一个
`RECIPIENT_ALIAS_INVALID`	花名为空、过长或包含控制字符	提交不超过 50 字符的准确花名
`RECIPIENT_ALIAS_NOT_FOUND`	素材平台内部目录没有找到该花名对应的钉钉 `userId`	核对准确花名或改用钉钉 `userId`，不得猜测重试
`RECIPIENT_ALIAS_DIRECTORY_UNAVAILABLE`	素材平台内部目录暂时不可用	不入队，稍后重试或联系维护人
`ACTION_URL_INVALID`	`actionUrl` 过长或包含非法控制字符	修正链接后重试
`IDEMPOTENCY_KEY_INVALID`	幂等键为空或过长	按统一格式生成稳定键
`MESSAGE_FIELDS_REQUIRED`	收件人、标题或内容缺失	补齐字段
`MESSAGE_TOO_LONG`	标题、正文或按钮超长	压缩内容，把详情放回业务页面
`TITLE_BRAND_RESERVED`	业务标题自行添加了“由壹点”品牌前缀	只提交业务标题
`IDEMPOTENCY_CONFLICT`	同一幂等键对应了不同内容	修复幂等键或业务数据，不得随机换键规避
`NOT_FOUND`	记录不存在或跨项目访问	检查投递 ID 和项目身份
`INTERNAL_ERROR`	通知中心内部异常	原幂等键退避重试并通知维护人员
`FLOW_CONTROLLED`	钉钉明确拒绝本次请求并要求限流	接入方等待，通知中心内部自动有限重试
`INVALID_USER`	钉钉确认收件人内部员工 `userId` 无效或不存在	接入方修正人员数据，不得改用邮箱或姓名重试
`FILTERED_USER`	收件人不在统一机器人可见范围内	由通知中心维护人核对应用权限范围
`DELIVERY_OUTCOME_UNKNOWN`	请求可能已经送达，无法安全确认	停止自动重试，人工核验后决定是否补发

投递进入 failed 时，还应记录返回中的 lastErrorCode 和 lastErrorMessage，但不要直接把内部错误原文展示给最终用户。

5. 业务端重试原则

连接失败或 HTTP 500 时可以有限重试，必须复用原 idempotencyKey，每次生成新 nonce。
HTTP 200 / 202 后不要重新创建通知，改为查询返回的投递 ID。
HTTP 401 / 409 / 422 默认不自动重试；先修正配置或请求。
通知中心内部会处理明确未受理的钉钉限流等情况，业务项目不得再叠加无限重试。
DELIVERY_OUTCOME_UNKNOWN 表示发送结果无法确定。为避免用户收到重复单聊，通知中心会停止自动重试；业务负责人确认后才能人工补发。

6. 建议监控

业务项目至少记录：

业务事件 ID
idempotencyKey
通知中心投递 id
收件人钉钉 userId
最近一次查询状态
lastErrorCode

禁止记录项目密钥、签名原文中的密钥、钉钉 AppSecret、免登码和一次性登录票据。

5.7 KiB Raw Blame History Unescape Escape