先把错误分层
要让错误率这个数字有意义，先得给错误分类：客户端错误（参数不合法、鉴权失败、被限流）不该计入服务故障，服务端错误（5xx）与超时才算。口径一旦固定下来，错误率才能作为告警与 SLO 的依据，也才能和业务方对得上账。
基本信息
| 参数错误 | 请求无效，客户端侧 |
|---|---|
| 鉴权错误 | 401/403，网关拒绝 |
| 429 | 限流或过载，保护性 |
| 5xx | 服务侧失败，计入故障 |
| 超时 | 单独归类看趋势 |
典型使用场景
- 给 SLO 定义错误率的分子与分母
- 区分「服务坏了」与「用户传错了」
- 做分级告警，避免阈值钝化
- 与业务方对账时口径一致
- 复盘时判断真实影响面
- 给业务方提供分层后的错误看板，避免把客户端错误当成服务问题
- 把口径写进运行手册，交接时逐条确认一遍
- 把分层规则写进网关配置的注释，新人接手时能直接看懂
- 复盘时把每类错误的占比写成结论，作为下一次改进的输入
错误体结构（示意）
错误体结构（示意）
{
"error": {
"message": "...",
"type": "invalid_request_error",
"code": null
}
}
// 网关按 status 与 type 归类后再进统计管道分层与归类
| 错误类型 | 归入 | 说明 |
|---|---|---|
| 参数错误 | 客户端 | 不计入服务故障 |
| 鉴权失败 | 客户端 | 与权限配置有关 |
| 429 | 保护性 | 单列一类便于观察 |
| 5xx 与超时 | 服务端 | 计入可用性 |
统计分母的口径要固定，例如「有效请求」是否包含 429：口径一改历史对比就失效，所以必须写进运行手册。
网关与引擎的错误分类要能对上：同一个失败在网关记成 502、在引擎里是超时，两侧口径不一致时对账永远对不上。
分类粒度够用就好：太细维护成本高、没人看，太粗又定位不到问题，按实际排障习惯定档。