首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >API 错误码不统一?六类错误响应的落地模板(JSON示例+表格)

API 错误码不统一?六类错误响应的落地模板(JSON示例+表格)

作者头像
安全风信子
发布2025-11-18 18:58:59
发布2025-11-18 18:58:59
150
举报
文章被收录于专栏:AI SPPECHAI SPPECH

一句话承诺:提供可抄的错误响应模板与分类表,快速统一前后端的错误处理。


分类表

分类

典型HTTP

建议码段

示例

验证错误

400

1000-1999

字段缺失、格式错误

未认证

401

2000-2099

Token无效或过期

无权限

403

2100-2199

角色不匹配

资源未找到

404

3000-3099

ID不存在

业务冲突

409

4000-4099

状态不允许

服务器错误

500

5000-5999

异常未捕获

JSON 模板(可统一落地)

代码语言:javascript
复制
{
  "code": 1001,
  "http": 400,
  "message": "字段校验失败",
  "details": [
    { "field": "email", "issue": "格式不正确" },
    { "field": "age", "issue": "必须为正整数" }
  ],
  "traceId": "abc-123"
}
代码语言:javascript
复制
{
  "code": 2001,
  "http": 401,
  "message": "未认证或Token过期",
  "details": [],
  "traceId": "abc-123"
}
代码语言:javascript
复制
{
  "code": 5001,
  "http": 500,
  "message": "服务器内部错误",
  "details": [],
  "traceId": "abc-123"
}

少量解释

  • 把业务错误码与HTTP分层:HTTP是传输层信号,业务码是领域层细化。
  • 统一输出字段:code、http、message、details、traceId,便于日志聚合与前端展示。
  • 对验证错误提供 details 数组,便于前端逐项提示。

常见坑与替代法

  • 坑:把所有错误都返回 200。替代:语义化HTTP码,有助于中间件与缓存策略。
  • 坑:错误码无规则。替代:按分类预留码段,避免冲突。
  • 坑:未提供 traceId。替代:贯穿全链路的请求ID,便于定位问题。

下一篇预告

JWT“过期刷新”太混乱?最简单的刷新策略与黑名单设计(时序图)。

本文参与 腾讯云自媒体同步曝光计划,分享自作者个人站点/博客。
原始发表:2025-10-23,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 分类表
  • JSON 模板(可统一落地)
  • 少量解释
  • 常见坑与替代法
  • 下一篇预告
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档