Skip to content

企业级接口错误码设计规范

1 引言

1.1 目的

为统一企业内部各业务系统接口的错误码定义标准,提升接口的可维护性、可调试性和用户体验,降低跨团队协作成本,明确错误场景的归类与处理原则,特制定本规范。本规范适用于企业所有内部服务接口、外部开放接口及第三方对接接口的错误码设计、定义与使用。

1.2 适用范围

本规范覆盖企业内所有研发团队(包括后端、前端、移动端)、测试团队、运维团队及对接的第三方合作方;适用于HTTP/HTTPS、RPC、WebSocket等各类接口协议的错误码设计与返回格式定义。

1.3 术语与定义

  • 错误码:用于唯一标识接口调用过程中出现的特定错误场景的编码,由固定格式的字符或数字组合构成。

  • 系统级错误:由基础架构、核心服务(如数据库、缓存、消息队列)或框架层面出现异常导致的错误,与具体业务逻辑无关。

  • 业务级错误:由业务规则校验、业务流程执行失败等业务逻辑相关场景导致的错误。

  • 参数级错误:由接口入参缺失、格式错误、范围无效等参数校验不通过导致的错误。

  • 错误信息:与错误码对应的、用于描述错误场景的人性化文本,可分为开发调试用详细信息和用户展示用简化信息。

2 设计原则

2.1 统一性原则

全企业范围内采用统一的错误码编码格式、分类规则和返回格式,避免不同系统各自定义错误码导致的混乱。同一错误场景必须对应唯一错误码,同一错误码必须对应唯一错误语义,禁止重复或歧义定义。

2.2 可扩展性原则

错误码编码结构需预留足够的扩展位,支持新增业务系统、新增错误类型时无需调整现有编码规则。编码长度和分段格式固定,便于后续系统自动化解析和管理。

2.3 易读性与可定位性原则

错误码应具备语义关联性,通过编码分段可快速识别错误所属系统、错误类型(系统级/业务级/参数级),减少调试时的查询成本。错误信息需清晰、准确,同时提供开发层面的调试信息(如错误ID、具体异常栈摘要)和用户层面的友好提示。

2.4 兼容性原则

错误码设计需考虑新旧系统的兼容过渡,对于历史系统的旧错误码,应制定映射规则逐步迁移至新规范。同时支持与第三方接口错误码的适配,可通过网关或适配层进行编码转换。

2.5 精简性原则

错误码定义应精准覆盖核心错误场景,避免过度细化导致编码冗余。对于同类错误场景,可通过错误信息补充差异,而非新增错误码。

3 错误码编码结构

3.1 编码格式

采用“分层分段式”编码结构,格式为:ABBCCCDDD,总长度为9位(无分隔符),各分段含义如下:

分段 长度 类型 含义 取值范围及说明
A(一级码) 1位 数字 错误类型标识 0:成功;1:系统级错误;2:业务级错误;3:参数级错误;4:权限级错误;5:第三方依赖错误;6-9:预留扩展类型
BB(二级码) 2位 数字 系统/模块标识 00:通用系统;01:用户中心系统;02:订单系统;03:支付系统;04:商品系统;05-99:预留业务系统编码(需登记备案)
CCC(三级码) 3位 数字 错误大类标识 对应二级系统下的具体业务域或错误场景大类,如001:资源不存在;002:状态异常;003:数量超限等(各系统自行定义,需备案)
DDD(四级码) 3位 数字 具体错误场景标识 对应三级错误大类下的具体错误场景,如001:用户ID不存在;002:手机号已注册等(各系统自行定义,需备案)
## 3.2 特殊编码说明
  • 成功编码:固定为000000000,表示接口调用成功且业务逻辑执行完成。

  • 通用错误编码:以“00”(二级码)开头,适用于所有系统的通用错误场景,如100001001(系统内部未知错误)、300001001(必填参数缺失)。

  • 预留编码:各分段中未明确分配的取值范围为预留扩展位,新增系统或错误类型时需向企业架构组申请,登记备案后使用。

4 错误码分类及示例

4.1 系统级错误(A=1)

定义:由服务器、数据库、缓存、消息队列、系统框架等基础组件异常导致的错误,无法通过业务逻辑调整修复,需运维或架构团队介入处理。

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
100001001 系统未知错误 系统繁忙,请稍后重试 系统内部未知异常,错误ID:{errorId},异常信息:{exceptionMsg} 系统抛出未捕获的异常
100002001 数据库连接失败 系统繁忙,请稍后重试 数据库连接池耗尽或连接参数错误,错误ID:{errorId} 应用无法建立数据库连接
100003001 缓存服务异常 系统繁忙,请稍后重试 Redis/Memcached服务连接失败或操作超时,错误ID:{errorId} 缓存服务不可用或操作异常
## 4.2 业务级错误(A=2)

定义:业务逻辑执行过程中因不符合业务规则、业务状态异常等导致的错误,需业务方调整参数或流程后重新尝试。

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
202001001 订单不存在 当前订单不存在,请核对订单号 订单号:{orderNo} 对应的订单记录不存在 查询、操作不存在的订单
202002001 订单状态异常 订单状态不允许此操作,请刷新后重试 订单号:{orderNo} 当前状态为{orderStatus},不支持{operation}操作 对已取消、已完成的订单执行支付、发货等操作
203003001 账户余额不足 您的账户余额不足,无法完成支付 用户ID:{userId} 账户余额:{balance},需支付金额:{amount},余额不足 支付时账户余额小于待支付金额
## 4.3 参数级错误(A=3)

定义:接口入参未通过校验,如参数缺失、格式错误、类型不匹配、取值超出范围等。

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
300001001 必填参数缺失 缺少必要参数,请补充完整 必填参数:{paramName} 缺失,参数位置:{paramLocation}(query/form/body) 未传递接口定义的必填参数
300002001 参数格式错误 参数格式不正确,请核对后重试 参数:{paramName} 格式错误,期望格式:{expectedFormat},实际值:{actualValue} 参数格式不符合要求(如手机号、邮箱、日期格式错误)
301003001 用户ID格式错误 用户ID格式不正确,请输入有效的用户ID 参数:userId 格式错误,期望为数字类型,实际值:{actualValue} 用户中心系统接口的userId参数非数字类型
## 4.4 权限级错误(A=4)

定义:因用户未登录、登录状态过期、无对应操作权限等导致的错误。

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
400001001 未登录 请先登录后再执行此操作 用户未登录,缺少有效的身份凭证(token/cookie) 未登录用户访问需要登录的接口
400002001 登录状态过期 登录状态已过期,请重新登录 用户身份凭证(token/cookie)已过期,token:{token},过期时间:{expireTime} 登录凭证过期后访问接口
402003001 无订单操作权限 您没有权限操作此订单 用户ID:{userId} 无订单号:{orderNo} 的{operation}操作权限 用户尝试操作他人订单或无对应订单权限的操作
## 4.5 第三方依赖错误(A=5)

定义:调用第三方服务(如支付渠道、短信服务商、地图接口等)时出现的错误,需根据第三方返回的错误信息进一步处理。

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
503001001 第三方支付服务异常 支付服务暂时不可用,请稍后重试 调用{paymentChannel}支付服务失败,第三方错误码:{thirdPartyCode},第三方错误信息:{thirdPartyMsg} 调用微信支付、支付宝等第三方支付接口失败
501002001 短信服务商接口异常 短信发送失败,请稍后重试 调用{smspProvider}短信服务失败,第三方错误码:{thirdPartyCode},错误信息:{thirdPartyMsg} 调用第三方短信接口发送验证码或通知短信失败
## 4.6 新增业务系统错误码示例

新增3个常见业务系统(物流系统、营销系统、财务系统),对应的二级系统编码分别为:05(物流系统)、06(营销系统)、07(财务系统),以下为各系统无分隔符错误码示例:

4.6.1 物流系统(二级码:05)

涵盖物流订单相关的业务级、参数级错误场景,错误码遵循“A05CCCDDD”格式(A为错误类型标识):

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
205001001 物流订单不存在 当前物流订单不存在,请核对物流单号 物流单号:{logisticsNo} 对应的订单记录不存在 查询、跟踪不存在的物流订单
205002001 物流状态异常 物流状态不允许此操作,请刷新后重试 物流订单号:{logisticsNo} 当前状态为{logisticsStatus},不支持{operation}操作 对已签收、已取消的物流订单执行拦截、改派等操作
305001001 物流单号格式错误 物流单号格式不正确,请输入有效的物流单号 参数:logisticsNo 格式错误,期望为字母+数字组合,实际值:{actualValue} 物流系统接口的物流单号参数不符合格式要求
### 4.6.2 营销系统(二级码:06)

涵盖营销活动相关的业务级、权限级错误场景,错误码遵循“A06CCCDDD”格式:

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
206001001 营销活动不存在 当前营销活动不存在,请核对活动ID 活动ID:{activityId} 对应的营销活动记录不存在 查询、参与不存在的营销活动
206002001 活动参与次数超限 您已超过该活动的最大参与次数,无法继续参与 用户ID:{userId} 参与活动ID:{activityId} 的次数已达上限{maxCount}次 用户超出营销活动设定的参与次数限制
406001001 无营销活动编辑权限 您没有权限编辑此营销活动 用户ID:{userId} 无活动ID:{activityId} 的编辑权限,当前角色:{userRole} 非活动创建者、管理员尝试编辑营销活动
### 4.6.3 财务系统(二级码:07)

涵盖财务凭证、对账相关的业务级、第三方依赖错误场景,错误码遵循“A07CCCDDD”格式:

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
207001001 财务凭证不存在 当前财务凭证不存在,请核对凭证号 凭证号:{voucherNo} 对应的财务凭证记录不存在 查询、审核不存在的财务凭证
207002001 对账失败 本期对账未通过,请核对收支数据后重试 对账周期:{accountPeriod} 收支数据不匹配,收入金额:{incomeAmount},支出金额:{expenseAmount} 财务系统月度、季度对账时收支数据不一致
507001001 税务接口调用失败 税务信息同步失败,请稍后重试 调用税务系统接口失败,第三方错误码:{thirdPartyCode},错误信息:{thirdPartyMsg} 财务系统向税务系统同步发票、纳税信息时调用失败
### 4.6.4 客服系统(二级码:08)

涵盖客服工单、咨询相关的业务级、参数级错误场景,错误码遵循“A08CCCDDD”格式:

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
208001001 客服工单不存在 当前客服工单不存在,请核对工单号 工单号:{workOrderNo} 对应的客服工单记录不存在 查询、跟进不存在的客服工单
208002001 工单状态异常 工单状态不允许此操作,请刷新后重试 工单号:{workOrderNo} 当前状态为{orderStatus},不支持{operation}操作 对已结案、已撤销的工单执行回复、转派等操作
308001001 工单类型参数错误 工单类型参数不正确,请选择有效的工单类型 参数:workOrderType 格式错误,期望取值[1:咨询,2:投诉,3:建议],实际值:{actualValue} 创建客服工单时传入无效的工单类型参数
### 4.6.5 采购系统(二级码:09)

涵盖采购订单、供应商相关的业务级、权限级错误场景,错误码遵循“A09CCCDDD”格式:

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
209001001 采购订单不存在 当前采购订单不存在,请核对采购单号 采购单号:{purchaseNo} 对应的采购订单记录不存在 查询、审核不存在的采购订单
209002001 供应商状态异常 该供应商状态异常,无法创建采购订单 供应商ID:{supplierId} 当前状态为{supplierStatus}(未审核/已禁用),不支持创建采购订单 向未审核或已禁用的供应商发起采购
409001001 无采购订单审核权限 您没有权限审核此采购订单 用户ID:{userId} 无采购订单{purchaseNo}的审核权限,当前角色:{userRole} 非采购审核角色用户尝试审核采购订单
### 4.6.6 支付系统(二级码:03)

涵盖支付流程、退款相关的业务级、第三方依赖错误场景,错误码遵循“A03CCCDDD”格式:

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
203001001 支付订单已关闭 当前支付订单已关闭,无法完成支付 支付订单号:{payNo} 已关闭,关闭原因:{closeReason} 对已超时关闭或手动关闭的支付订单发起支付
203002001 退款申请失败 退款申请提交失败,请稍后重试 支付订单号:{payNo} 未支付/已退款,不支持退款申请 对未支付或已完成退款的订单发起退款申请
503002001 第三方退款接口异常 退款处理中出现异常,请稍后查询结果 调用{paymentChannel}退款接口失败,第三方错误码:{thirdPartyCode},错误信息:{thirdPartyMsg} 调用微信/支付宝等第三方退款接口失败
### 4.6.7 消息系统(二级码:10)

涵盖消息发送、消息模板相关的业务级、参数级错误场景,错误码遵循“A10CCCDDD”格式:

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
210001001 消息模板不存在 当前消息模板不存在,请核对模板ID 模板ID:{templateId} 对应的消息模板记录不存在 使用不存在的模板发送消息
210002001 消息发送频率超限 消息发送频率过高,请稍后重试 用户ID:{userId} 向接收方{receiver}发送消息频率超限,当前频率:{currentFreq},限制频率:{limitFreq} 短时间内向同一接收方多次发送消息触发频率限制
310001001 接收方账号格式错误 接收方账号格式不正确,请核对后重试 参数:receiver 格式错误,期望为手机号/邮箱,实际值:{actualValue} 发送消息时传入无效格式的接收方账号
### 4.6.8 用户系统(二级码:01)

涵盖用户注册、信息修改相关的业务级、参数级错误场景,错误码遵循“A01CCCDDD”格式:

错误码 错误名称 错误信息(用户端) 错误信息(开发端) 适用场景
201001001 手机号已注册 该手机号已注册,请直接登录或找回密码 手机号:{phone} 已存在对应的用户记录,用户ID:{userId} 使用已注册的手机号重复注册
201002001 用户状态异常 您的账号状态异常,无法修改信息 用户ID:{userId} 当前状态为{userStatus}(已冻结/已注销),不支持信息修改 冻结/注销状态的用户尝试修改个人信息
301001001 密码格式错误 密码格式不正确,请输入8-20位字母+数字组合 参数:password 格式错误,未满足8-20位字母+数字组合要求,实际值:{actualValue} 注册/修改密码时输入不符合规则的密码
# 5 接口错误返回格式规范

5.1 通用返回格式

所有接口无论成功或失败,均采用统一的JSON格式返回,确保前端及第三方对接时解析逻辑一致。格式如下:

{
  "code": "string", // 错误码,成功时为"000000000"
  "message": "string", // 用户端友好错误信息,成功时为"success"
  "data": "object|null", // 接口返回的业务数据,失败时可为null
  "debugInfo": { // 开发调试信息,生产环境可隐藏
    "errorId": "string", // 错误唯一标识,用于日志追踪
    "exceptionMsg": "string", // 异常详细信息(可选)
    "thirdPartyInfo": "object|null", // 第三方依赖错误的详细信息(可选)
    "requestId": "string" // 接口请求唯一标识
  }
}

5.2 成功返回示例

{
  "code": "000000000",
  "message": "success",
  "data": {
    "userId": "10001",
    "userName": "张三",
    "phone": "13800138000"
  },
  "debugInfo": {
    "errorId": "",
    "exceptionMsg": "",
    "thirdPartyInfo": null,
    "requestId": "req20260107123456789"
  }
}

5.3 失败返回示例

{
  "code": "203003001",
  "message": "您的账户余额不足,无法完成支付",
  "data": null,
  "debugInfo": {
    "errorId": "err20260107123456790",
    "exceptionMsg": "用户ID:10001 账户余额:50 元,需支付金额:100 元,余额不足",
    "thirdPartyInfo": null,
    "requestId": "req20260107123456789"
  }
}

5.4 特殊场景处理

  • 批量接口错误:若接口支持批量操作(如批量创建订单、批量查询数据),当部分操作成功、部分失败时,需在data中返回详细的批量处理结果,包含每个子操作的错误码和错误信息,顶层code可仍为成功码(000000000),并在message中说明“部分操作成功”。

  • 流式接口错误:对于流式返回的接口(如文件下载、实时数据推送),若发生错误,需先返回错误码和错误信息的JSON对象,再终止流传输。

  • 生产环境隐藏调试信息:生产环境下,debugInfo字段可配置为不返回或仅返回errorId和requestId,避免泄露敏感信息。

6 错误码管理规范

6.1 错误码注册与备案

各业务系统新增错误码时,需向企业架构组提交《错误码注册申请表》,说明错误码编码、错误名称、适用场景、错误信息等内容,经审核通过后登记备案。备案信息需维护在企业统一的错误码管理平台,供所有团队查询。

6.2 错误码变更与废弃

已注册的错误码若需修改语义或适用场景,需重新提交申请并更新备案信息;若错误场景不再存在,需申请废弃,废弃后的错误码不得重新启用。废弃错误码需在管理平台标记为“废弃”,并注明废弃时间和替代方案(若有)。

6.3 错误码文档维护

企业需维护统一的错误码文档,包含错误码编码、错误类型、所属系统、适用场景、错误信息(用户端/开发端)、变更记录等信息。文档需实时更新,支持在线查询和下载,确保各团队使用最新的错误码规范。

7 实施与推广要求

7.1 新系统实施要求

所有新建系统必须严格遵循本规范设计和使用错误码,接口返回格式需符合第5章的要求。系统上线前,需由企业架构组对错误码设计和返回格式进行审核,审核通过后方可上线。

7.2 老系统迁移要求

现有老系统需制定错误码迁移计划,逐步将旧错误码映射至本规范定义的新错误码。迁移过渡期内,接口可同时返回新旧错误码(新错误码在code字段,旧错误码在扩展字段oldCode中),待前端及相关依赖系统适配完成后,移除旧错误码。迁移完成时间需符合企业统一的技术改造规划。

7.3 培训与监督

企业架构组需组织针对本规范的专项培训,确保所有研发、测试、运维人员理解并掌握规范要求。同时,将错误码规范的遵循情况纳入系统架构评审和代码审查范围,定期开展合规性检查,对不符合规范的系统督促整改。

8 新增业务系统错误码对照表

本文档汇总新增业务系统(物流、营销、财务、客服、采购、支付、消息、用户)的错误码信息,便于各团队查询使用,具体内容如下:

系统名称 二级码 错误码 错误名称 错误类型 错误信息(用户端) 适用场景
物流系统 05 205001001 物流订单不存在 业务级 当前物流订单不存在,请核对物流单号 查询、跟踪不存在的物流订单
205002001 物流状态异常 业务级 物流状态不允许此操作,请刷新后重试 对已签收、已取消的物流订单执行拦截、改派等操作
305001001 物流单号格式错误 参数级 物流单号格式不正确,请输入有效的物流单号 物流系统接口的物流单号参数不符合格式要求
营销系统 06 206001001 营销活动不存在 业务级 当前营销活动不存在,请核对活动ID 查询、参与不存在的营销活动
206002001 活动参与次数超限 业务级 您已超过该活动的最大参与次数,无法继续参与 用户超出营销活动设定的参与次数限制
406001001 无营销活动编辑权限 权限级 您没有权限编辑此营销活动 非活动创建者、管理员尝试编辑营销活动
财务系统 07 207001001 财务凭证不存在 业务级 当前财务凭证不存在,请核对凭证号 查询、审核不存在的财务凭证
207002001 对账失败 业务级 本期对账未通过,请核对收支数据后重试 财务系统月度、季度对账时收支数据不一致
507001001 税务接口调用失败 第三方依赖级 税务信息同步失败,请稍后重试 财务系统向税务系统同步发票、纳税信息时调用失败
客服系统 08 208001001 客服工单不存在 业务级 当前客服工单不存在,请核对工单号 查询、跟进不存在的客服工单
208002001 工单状态异常 业务级 工单状态不允许此操作,请刷新后重试 对已结案、已撤销的工单执行回复、转派等操作
308001001 工单类型参数错误 参数级 工单类型参数不正确,请选择有效的工单类型 创建客服工单时传入无效的工单类型参数
采购系统 09 209001001 采购订单不存在 业务级 当前采购订单不存在,请核对采购单号 查询、审核不存在的采购订单
209002001 供应商状态异常 业务级 该供应商状态异常,无法创建采购订单 向未审核或已禁用的供应商发起采购
409001001 无采购订单审核权限 权限级 您没有权限审核此采购订单 非采购审核角色用户尝试审核采购订单
支付系统 03 203001001 支付订单已关闭 业务级 当前支付订单已关闭,无法完成支付 对已超时关闭或手动关闭的支付订单发起支付
203002001 退款申请失败 业务级 退款申请提交失败,请稍后重试 对未支付或已完成退款的订单发起退款申请
503002001 第三方退款接口异常 第三方依赖级 退款处理中出现异常,请稍后查询结果 调用微信/支付宝等第三方退款接口失败
消息系统 10 210001001 消息模板不存在 业务级 当前消息模板不存在,请核对模板ID 使用不存在的模板发送消息
210002001 消息发送频率超限 业务级 消息发送频率过高,请稍后重试 短时间内向同一接收方多次发送消息触发频率限制
310001001 接收方账号格式错误 参数级 接收方账号格式不正确,请核对后重试 发送消息时传入无效格式的接收方账号
用户系统 01 201001001 手机号已注册 业务级 该手机号已注册,请直接登录或找回密码 使用已注册的手机号重复注册
201002001 用户状态异常 业务级 您的账号状态异常,无法修改信息 冻结/注销状态的用户尝试修改个人信息
301001001 密码格式错误 参数级 密码格式不正确,请输入8-20位字母+数字组合 注册/修改密码时输入不符合规则的密码
# 9 附则

9.1 规范解释权

本规范的解释权归企业架构组所有。

9.2 规范修订

本规范根据企业业务发展和技术升级需求,由企业架构组牵头定期修订。修订后需及时发布并组织培训,确保各团队同步执行。

9.3 生效日期

本规范自发布之日起生效。

8.1 规范解释权

本规范的解释权归企业架构组所有。

8.2 规范修订

本规范根据企业业务发展和技术升级需求,由企业架构组牵头定期修订。修订后需及时发布并组织培训,确保各团队同步执行。

8.3 生效日期

本规范自发布之日起生效。

(注:文档部分内容可能由 AI 生成)