---
source: ../../../core/error-code-standards.md
source_version: 1.2.0
translation_version: 1.1.0
last_synced: 2026-01-08
status: outdated
---

> **语言**: [English](../../../core/error-code-standards.md) | [简体中文](../../zh-TW/core/error-code-standards.md) | 简体中文

# 错误码标准

**版本**: 1.0.0
**最后更新**: 2025-12-30
**适用范围**: 所有需要统一错误处理的应用程序

---

## 目的

本标准定义统一的错误码管理规范，以提升调试效率、监控能力和用户体验。

---

## 错误码格式

### 标准格式

```
<前缀>_<类别>_<编号>
```

| 组成 | 说明 | 示例 |
|------|------|------|
| 前缀 | 应用/服务标识 | AUTH, PAY, USR |
| 类别 | 错误类别 | VAL, SYS, BIZ |
| 编号 | 唯一数字标识 | 001, 100, 404 |

### 示例

```
AUTH_VAL_001    → 认证验证错误
PAY_SYS_503     → 支付系统不可用
USR_BIZ_100     → 用户业务规则违反
API_NET_408     → API 网络超时
```

---

## 错误类别

| 代码 | 类别 | 说明 | HTTP 状态 |
|-----|------|------|----------|
| VAL | 验证 | 输入验证失败 | 400 |
| BIZ | 业务 | 业务规则违反 | 422 |
| AUTH | 认证 | 安全相关错误 | 401/403 |
| SYS | 系统 | 内部系统错误 | 500 |
| NET | 网络 | 通信/连接问题 | 502/503 |

### 验证错误 (VAL)

| 代码范围 | 说明 |
|---------|------|
| *_VAL_001-099 | 字段验证 |
| *_VAL_100-199 | 格式验证 |
| *_VAL_200-299 | 约束验证 |

### 业务逻辑错误 (BIZ)

| 代码范围 | 说明 |
|---------|------|
| *_BIZ_001-099 | 状态违反 |
| *_BIZ_100-199 | 规则违反 |
| *_BIZ_200-299 | 限制违反 |

---

## 错误响应格式

### 单个错误

```json
{
  "success": false,
  "error": {
    "code": "AUTH_VAL_001",
    "message": "邮箱为必填字段",
    "field": "email",
    "requestId": "req_abc123"
  }
}
```

### 多个错误

```json
{
  "success": false,
  "errors": [
    {
      "code": "AUTH_VAL_001",
      "message": "邮箱为必填字段",
      "field": "email"
    },
    {
      "code": "AUTH_VAL_201",
      "message": "密码至少需要 8 个字符",
      "field": "password"
    }
  ],
  "requestId": "req_abc123"
}
```

---

## 国际化 (i18n)

### 消息键格式

```
error.<前缀>.<类别>.<编号>
```

### 翻译文件示例

```yaml
# zh-CN.yaml
error:
  auth:
    val:
      001: "邮箱为必填字段"
      101: "邮箱格式无效"
    auth:
      001: "用户名或密码错误"
      201: "会话已过期"
```

---

## 快速参考卡

### 代码格式

```
<前缀>_<类别>_<编号>
AUTH_VAL_001
```

### 类别速查

| 代码 | 类别 | HTTP | 用途 |
|-----|------|------|------|
| VAL | 验证 | 400 | 输入验证 |
| BIZ | 业务 | 422 | 业务规则 |
| AUTH | 认证 | 401/403 | 安全 |
| SYS | 系统 | 500 | 内部错误 |
| NET | 网络 | 502/503 | 连接 |

### 检查清单

- [ ] 每个错误有唯一代码
- [ ] 类别符合错误类型
- [ ] 用户消息已本地化
- [ ] HTTP 状态正确
- [ ] 错误已记录文档
- [ ] 代码已注册

---

## 相关标准

- [日志标准](logging-standards.md) - 错误日志实践
- [API 文档标准](api-documentation-standards.md) - 错误响应文档

---

## 许可证

本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。
