跳至主要內容

错误码设计

错误码是 API 设计的重要组成部分，好的错误码应该让开发者快速定位问题来源、实现跨团队的标准化沟通。

提示

阿里巴巴错误码设计规范与实践

错误码设计原则

错误码的制定原则：快速溯源、沟通标准化

好的错误码应该回答：

  1. 是谁的错？（错误来源）
  2. 错在哪？（具体问题）

强制规则

这些规则必须强制遵守，是代码质量的底线。

  1. 错误码不体现版本号和错误等级信息。

    • 说明：错误码以不断追加的方式进行兼容

  2. 全部正常，但不得不填充错误码时返回五个零：00000

  3. 错误码为字符串类型，共5位，分成两个部分：XYYYY，其中 X 是错误来源（A/B/C），YYYY 是四位数字编号（0001-9999）。

来源含义说明
A用户端错误参数错误、版本过低、支付超时等
B系统执行出错业务逻辑出错、程序健壮性差
C第三方服务出错CDN出错、消息投递超时等

  1. 编号不与公司业务架构或组织架构挂钩，以先到先得的原则在统一平台上进行审批。

  2. 错误码使用者避免随意定义新的错误码。尽可能在原有错误码附表中找到语义相同或相近的错误码。

  3. 错误码不能直接输出给用户作为提示信息使用。

    • 说明：堆栈(stack_trace)、错误信息(error_message)、错误码(error_code)、提示信息(user_tip)是一个和谐整体

错误码结构

一级宏观错误码

错误码含义
A0001用户端错误
B0001系统执行出错
C0001调用第三方服务出错

二级宏观错误码示例

B类（系统执行出错）

错误码含义
B0100系统执行超时
B0200系统容灾功能被触发
B0210系统限流
B0220系统功能降级
B0300系统资源异常
B0310系统资源耗尽
B0311系统磁盘空间耗尽
B0312系统内存耗尽

C类（第三方服务）

错误码含义
C0100中间件服务出错
C0110RPC服务出错
C0120消息服务出错
C0130缓存服务出错
C0140配置服务出错
C0200第三方系统执行超时
C0300数据库服务出错

推荐规则

这些规则建议遵守，有助于提升代码质量和可维护性。

  1. 错误码之外的业务独特信息由error_message来承载。
  2. 在获取第三方服务错误码时，向上抛出允许本系统转义，由C转为B。

错误码与HTTP状态码的关系

错误码的后三位编号与HTTP状态码没有任何关系。

HTTP状态码含义错误码示例
200成功00000
400请求错误A0401
401未授权A0301
403禁止访问A0302
500服务器错误B0001

API响应格式

{
    "code": "00000",
    "message": "一切ok",
    "data": {},
    "traceId": "abc123"
}

错误响应：

{
    "code": "A0401",
    "message": "包含非法恶意跳转链接",
    "data": null,
    "traceId": "abc123"
}

错误码命名建议

使用纯数字编排不利于感性记忆和分类。推荐使用 XYYYY 结构：X 字母标识错误来源（A 用户端、B 系统、C 第三方），YYYY 数字标识具体错误。这种结构让开发者一眼判断"是谁的错"和"错在哪"，无需查阅文档即可初步定位问题。

适用场景

场景错误码策略原因
对外开放 APIXYYYY 五位结构跨团队标准化沟通
内部微服务简化错误码 + HTTP 状态码减少维护成本
第三方服务对接C 类错误码 + 转义机制区分内外部错误来源
多端统一响应标准化 API 响应格式code + message + data + traceId

FAQ

Q: 错误码和 HTTP 状态码有什么关系？ A: 没有直接关系。HTTP 状态码表示请求的处理结果（200 成功、400 参数错误、500 服务器错误），错误码表示具体的业务错误（A0401 包含非法链接、B0100 系统超时）。两者配合使用：HTTP 状态码用于网关和负载均衡层判断，错误码用于业务层精确定位。

Q: 错误码需要体现版本号吗？ A: 不需要。错误码以追加方式兼容新版本，不删除旧错误码。如果错误码包含版本号，版本升级时所有调用方都需要修改错误码解析逻辑，维护成本极高。

Q: 第三方服务的错误码如何处理？ A: 获取第三方服务错误码后，向上抛出时允许本系统转义，由 C 类转为 B 类。这样调用方只需要处理 A/B 两类错误码，无需关心底层依赖的第三方服务细节。转义时保留原始错误信息在 error_message 中，便于排查。