错误码 ​

DAT 官方支持的各服务库共用的错误码。

每个码都带有 影响、重试 两个值，部分还会额外带上 可疑 标签。

影响 — 服务受到多大冲击 ​

这是设置告警的依据，只看一件事：“现在服务停了吗”。

无影响 不是告警的对象。如果一条错误输入就要让所有值班人员去看，告警本身就失去意义了。

可疑 — 持续出现就要排查 ​

带 可疑 标签的码，只出现一次时属于正常运行的一部分。客户端随时可能发来错误的值，把它过滤掉正是库的本职。

但如果这类错误持续发生，或者从某个来源集中涌来，那就是两种情况之一。

• 配置异常 — 部署有误、还残留着旧版客户端、或者证书对不上。
• 攻击尝试 — 有人在篡改令牌或密钥、试图通过验证，或者在探测哪些值有效。

所以这些码正确的做法是把计数做成指标，只在超过阈值时才通知。

重试 ​

令牌 ​

收到的令牌字符串本身的问题。

证书 ​

证书字符串的格式，以及该证书现在是否可用的问题。

DAT_CERT_NOT_FOUND 和 DAT_CERT_NOT_SYNCED 表面症状相同，但处理方式不同。前者是从未签发过的 cid，等下去也不会出现；后者只要同步跟上就会消失。

DAT_CERT_NOT_FOUND 出现一次过滤掉即可，但如果突然增多，就说明分发对不上了，或者有伪造令牌在流通。

签名 ​

加密 ​

secure 载荷的加解密问题。

空的 secure 载荷不是错误。 空输入得到空输出，不会产生任何错误码。

在跳过签名验证的路径上，GCM 标签是唯一的完整性检查。因此不把 DAT_CRYPTO_TAG_MISMATCH 和其他解密失败归为同一个码。

密钥 ​

看起来相似但完全不同的三个：

管理器 ​

持有证书并用于签发、验证的对象的状态。

DAT_MANAGER_NO_ISSUABLE_CERTIFICATE 的原因（cause）是以下四者之一。每种原因该做的事完全不同。

如果签发服务器被配置成只接收仅供验证的证书，出来的就是 DAT_CERT_VERIFY_ONLY。等多久都不会好，所以不属于重试的范畴。

配置 ​

调用方传入的值有问题。CONFIG 系全部是必须改代码的错误，运行中出现就说明部署有误。

内部 ​

运行环境与运行时的问题。

DAT_INTERNAL_UNAVAILABLE 修好部署环境就能解决，而 DAT_INTERNAL_UNKNOWN 多半是运行时故障或库的 bug。

CMS 同步 ​

不使用 CMS 同步就不会出现这些码。

被判定为同步永久失败的码（UNAUTHORIZED、FORBIDDEN、ENDPOINT_NOT_FOUND、MALFORMED、IMPORT_FAILED）全部是致命。重试也解决不了，而证书还在不断过期，放着不管服务必然会停。

反过来，UNREACHABLE、SERVER_ERROR 属于部分。现有证书继续工作，下个周期通常会自行恢复 — 但一直失败下去最终会升级成致命。 请以连续失败次数为基准设置告警。

服务器 ​

CMS 服务器产生的码。客户端不会产生这些码，只会收到。

响应信封：

{
  "code": "DAT_REQ_ALG_UNSUPPORTED",
  "details": { "algorithm": "BOGUS-ALG" }
}

在生成和处理证书过程中出现的错误，服务器同样直接使用上面的公共码（DAT_CERT_*、DAT_KEY_*、DAT_CONFIG_*）。

收到服务器的码之后 ​

客户端会用自己的 CMS 码把服务器的码包起来，原始码保存在 cause 中。

按症状查找 ​

附录 ​

错误码语法 ​

DAT_<领域>_<原因>

• 同一原因出现在不同领域时，原因名是相同的。DAT_TOKEN_MALFORMED 和 DAT_CERT_MALFORMED 只是对象不同，含义一致。
• _UNKNOWN 是各领域的兜底专用，不会用作“未知算法”之类的其他含义（那是 _UNSUPPORTED）。
• 错误码字符串是公开契约。消息可以随意改，但码不改。

各客户端的取用方式 ​

安全事件 只在伪造、篡改已经确定的两种情况（DAT_SIG_MISMATCH、DAT_CRYPTO_TAG_MISMATCH）下返回 true。本文档的 可疑 标签范围更宽（还包括被篡改的令牌、密钥和请求），目前只是文档层面的分类，并未通过客户端 API 暴露。

影响 等级同样是文档层面的分类，因为同一个码在不同地方发生时打击并不相同 — 例如 DAT_KEY_INVALID 在过滤收到的令牌时没有影响，但如果是在 CMS 同步过程中读证书时出现，整个同步就会失败。

下层原因不会被丢弃。 DAT_MANAGER_NO_ISSUABLE_CERTIFICATE 和 DAT_CMS_IMPORT_FAILED 通过各语言的异常链（cause / __cause__ / InnerException / Unwrap()）传递原因。