| name | errors |
| description | 设计一致的错误码，遵循 PREFIX_CATEGORY_NUMBER 格式。
使用时机：定義错误码、建立错误处理、设计 API。
关鍵字：error code, error handling, error format, API errors, 错误码, 错误处理。
|
| source | ../../../../skills/error-code-guide/SKILL.md |
| source_version | 1.0.0 |
| translation_version | 1.0.0 |
| last_synced | "2026-01-08T00:00:00.000Z" |
| status | current |
错误码指南
语言: English | 简体中文
版本: 1.0.0
最後更新: 2025-12-30
適用範圍: Claude Code Skills
目的
此技能幫助设计一致的错误码，遵循标准格式，实現更好的除錯、監控和使用者体驗。
快速參考
错误码格式
<前綴>_<类别>_<编号>
| 元素 | 说明 | 範例 |
|---|
| 前綴 (PREFIX) | 应用/服务識别码 | AUTH, PAY, USR |
| 类别 (CATEGORY) | 错误类别 | VAL, SYS, BIZ |
| 编号 (NUMBER) | 唯一數字識别码 | 001, 100, 404 |
範例
AUTH_VAL_001 → 认证验证错误
PAY_SYS_503 → 付款系统無法使用
USR_BIZ_100 → 使用者商业規則違規
API_NET_408 → API 网络逾时
错误类别
| 类别 | 全名 | 说明 | HTTP 状态码 |
|---|
| VAL | Validation | 客户端输入验证失败 | 400 |
| BIZ | Business | 商业規則違規 | 422 |
| SYS | System | 內部系统错误 | 500 |
| NET | Network | 通訊错误 | 502/503/504 |
| AUTH | Auth | 安全相关错误 | 401/403 |
类别编号範圍
| 範圍 | 说明 | 範例 |
|---|
| *_VAL_001-099 | 欄位验证 | 缺少必填欄位 |
| *_VAL_100-199 | 格式验证 | 電子郵件格式無效 |
| *_VAL_200-299 | 約束验证 | 密码太短 |
| *_BIZ_001-099 | 状态違規 | 订单已取消 |
| *_BIZ_100-199 | 規則違規 | 超過 30 天無法退貨 |
| *_BIZ_200-299 | 限制違規 | 超過每日限制 |
| *_AUTH_001-099 | 认证 | 帳号密码错误 |
| *_AUTH_100-199 | 授权 | 权限不足 |
| *_AUTH_200-299 | Token/Session | Token 已過期 |
HTTP 状态码对应
| 类别 | HTTP 状态码 | 说明 |
|---|
| VAL | 400 | Bad Request |
| BIZ | 422 | Unprocessable Entity |
| AUTH (001-099) | 401 | Unauthorized |
| AUTH (100-199) | 403 | Forbidden |
| SYS | 500 | Internal Server Error |
| NET | 502/503/504 | Gateway errors |
详细指南
完整标准請參考：
AI 優化格式（节省 Token）
AI 助手可使用 YAML 格式文件以減少 Token 使用量：
- 基礎标准：
ai/standards/error-codes.ai.yaml
错误响应格式
单一错误
{
"success": false,
"error": {
"code": "AUTH_VAL_001",
"message": "電子郵件为必填欄位",
"field": "email",
"requestId": "req_abc123"
}
}
多个错误
{
"success": false,
"errors": [
{
"code": "AUTH_VAL_001",
"message": "電子郵件为必填欄位",
"field": "email"
},
{
"code": "AUTH_VAL_201",
"message": "密码至少需要 8 个字元",
"field": "password"
}
],
"requestId": "req_abc123"
}
內部错误物件
interface ApplicationError {
code: string;
message: string;
userMessage: string;
userMessageKey: string;
field?: string;
details?: object;
timestamp: string;
requestId: string;
}
國际化 (i18n)
消息鍵值格式
error.<前綴>.<类别>.<编号>
翻譯文件範例
error:
auth:
val:
001: "Email is required"
101: "Invalid email format"
auth:
001: "Invalid credentials"
error:
auth:
val:
001: "電子郵件为必填欄位"
101: "電子郵件格式無效"
auth:
001: "帳号或密码错误"
範例
✅ 良好的错误码
AUTH_VAL_001
AUTH_VAL_101
ORDER_BIZ_001
ORDER_BIZ_201
DB_SYS_001
SEC_AUTH_001
SEC_AUTH_201
❌ 不良的错误码
ERR_001
INVALID
error
AUTH_ERROR
检查清单
设置偵测
此技能支援项目特定设置。
偵测順序
- 检查程序码庫中現有的错误码模式
- 检查
CONTRIBUTING.md 中的错误码指南
- 若無找到，预设使用 PREFIX_CATEGORY_NUMBER 格式
首次设置
若未找到错误码标准：
- 建议：「此项目尚未设置错误码标准。您要建立错误码註冊表嗎？」
- 建议建立
errors/registry.ts：
export const ErrorCodes = {
AUTH_VAL_001: {
code: 'AUTH_VAL_001',
httpStatus: 400,
messageKey: 'error.auth.val.001',
description: '電子郵件欄位为必填',
},
} as const;
相关标准
版本历史
| 版本 | 日期 | 变更 |
|---|
| 1.0.0 | 2025-12-30 | 初始發布 |
授权
此技能採用 CC BY 4.0 授权。
來源: universal-dev-standards
Next Steps Guidance | 下一步引導
After /errors completes, the AI assistant should suggest:
錯誤碼設計已完成。建議下一步 / Error code design completed. Suggested next steps:
- 執行
/sdd 將錯誤碼設計納入正式規格 ⭐ Recommended / 推薦 — 確保錯誤碼在規格中有完整定義 / Ensure error codes are fully defined in specs
- 執行
/logging 設定結構化日誌以配合錯誤碼 — 讓錯誤碼與日誌系統整合 / Integrate error codes with logging system
- 執行
/tdd 為錯誤處理邏輯撰寫測試 — 確保每個錯誤碼都有對應的測試 / Ensure each error code has corresponding tests
Related Standards
Version History
| Version | Date | Changes |
|---|
| 1.0.0 | 2025-12-30 | Initial release |
License
This skill is released under CC BY 4.0.
Source: universal-dev-standards
