API 错误格式标准化工作流

概述

各接口错误形状不一，客户端就要为每处失败单独处理。定义含机器可读 code 与安全 message 的规范错误对象、把领域条件一致地映射到状态码、附带可追溯引用 ID，并以兼容期逐步迁移，可让错误处理收敛为一条路径。

关键步骤

1. 定义含稳定 code 与安全信息的规范错误对象。
2. 把领域条件映射到状态码并记录。
3. 为错误附加请求引用 ID 以便关联。
4. 以兼容期迁移不一致接口。

验证

• 各接口代表性失败返回规范形状。
• 状态码语义一致。
• 错误含可追溯引用 ID。
• 无堆栈信息泄露。

决策点

改变状态码会破坏客户端，应在新版本中引入并弃用旧的；校验细节应提供字段级且已脱敏的信息。

适用范围

本条目围绕「API 错误格式标准化工作流」给出可复制的步骤、验证方式与常见问题，适合需要按此流程落地的工程团队。执行时请结合自身上下文调整命令与阈值，并在变更前后留存证据，便于后续复核与回滚。

{
  "error": {
    "code": "validation_failed",
    "message": "Email is invalid",
    "details": [{ "field": "email", "issue": "invalid_format" }],
    "ref": "req_01J..."
  }
}