错误码两面分类

概念

一个错误码有两个面，不是二选一：

同一码可两面承载，但粒度不同：对外可能只呈现一个契约码，观测面细分根因类别。

判定流程（每个新状态码过三问）

1. Q1 对外可见：调用方能看到它且需要据此分支决策？——是 → 契约面（稳定契约 + @scenario 标注）；否 → 仅内部。
2. Q2 归因价值：能独立定位故障根因类别？——是 → 观测面（失败类别计数 + span error.type 属性）；否 → 不进，避免遥测噪音。
3. Q3 路径温度：冷路径（装配期）计数全量（无性能负担）；热路径（每请求）需采样（默认关）。

分层（两类错误码别混）

两层各自过三问，不混。

标准依据

• Google API Design Guide 错误模型（对外错误模型与内部诊断分离）
• OTel semantic conventions（error.type = span attribute + counter label，语义对齐可不引 SDK）
• gRPC 状态码惯例（码少而稳 vs 信息全）

边界

• OK/成功码两面不进（成功率是独立指标，不属于错误计数）。
• 上限用预算式校验而非拍绝对数：维度值 × 单位成本 ≤ 预算（随维度联动，比 magic number 正确）。
• 对外契约码删除/改名 = 破坏契约；观测面 label 变更无承诺。