错误文档最有价值的时候，不是只是让读者知道哪里失败了，而是帮助他们恢复。优先给出具体载荷示例，以及清晰说明下一步应该尝试什么。

常见结构

{
  "error": {
    "code": "invalid_request",
    "message": "The `title` field is required.",
    "request_id": "req_123"
  }
}

建议覆盖的内容

这个起步模板里的参考文档，最终至少应该说明：

  • 认证失败
  • 校验错误
  • 速率限制
  • 服务端瞬时失败

写作建议

当你记录一个错误码时，请同时包含：

  1. 它会在什么情况下触发
  2. 涉及哪些字段或 Header
  3. 客户端接下来应该怎么做

这样这个页面在真实生产排障时才会有用，而不仅仅是在最初 onboarding 时看一眼。