Skip to content

Latest commit

 

History

History
71 lines (58 loc) · 4.65 KB

error-codes.md

File metadata and controls

71 lines (58 loc) · 4.65 KB

契约 · 错误码全局段位表(v1.1 已定稿)

状态:已定稿(2026-09-01 评审通过;D1-D6 已拍板,口径为"业界标准优先于阿里手册",结论见 ../../docs/references/alibaba-java-manual-digest.md D 表。2026-09-18 升 v1.1:纯增量新增 2005 CAPTCHA_INVALID,随 captcha.md v1.0)。

D1 已拍板:采用 int32 数字段位 + 标识符(与 HTTP 状态码+reason phrase、gRPC code+name 的业界形态同构);不采用阿里 5 位字符串 A/B/C 方案——按"谁的错"分段偏客服排障视角,与按"谁拥有"分段的多仓治理诉求冲突,且 int32 对四栈类型系统与序列化最友好。

目标:任何栈、任何服务报出的同一个 code,语义唯一且同源。

段位分配

段位 归属 内容
0 yarch 成功
1xxx yarch 通用段:任何工程都需要的框架级错误
2xxx yarch 认证与权限段(IAM):登录态/凭证/授权
3xxx – 8xxx 业务工程 各业务仓自行注册(在业务仓 docs 登记后方可使用),yarch 不内置、不预测
9xxx 预留 不得使用

铁律:yarch 只拥有 0、1xxx、2xxx。出现租户/配额/INV 等领域语义的码,一律属于业务工程(如 ysaas 在其仓内登记 3xxx 段)。

通用段 1xxx(yarch 内置,各栈必须等价实现)

code 标识 message(默认文案) HTTP
1000 INTERNAL_ERROR 内部错误 500
1001 INVALID_ARGUMENT 参数校验失败 400
1002 MALFORMED_BODY 请求体格式错误 400
1003 (留空) — —
1004 NOT_FOUND 资源不存在 404
1005 CONFLICT 资源冲突 409
1006 RATE_LIMITED 触发限流 429
1007 IDEMPOTENCY_CONFLICT 幂等冲突:重复提交 409
1008 UPSTREAM_TIMEOUT 上游依赖超时 504
1009 UNAVAILABLE 服务暂不可用 503

1008 / 1009 可由网关层代替后端发出(后端不可达/熔断/过载场景,见 rest-response.md「网关故障面」);发出方必须保持 RestResponse 信封与 X-Trace-Id 回显。

认证与权限段 2xxx(yarch 内置)

code 标识 message(默认文案) HTTP
2001 UNAUTHORIZED 未认证 401
2002 CREDENTIALS_EXPIRED 凭证已过期 401
2003 FORBIDDEN 权限不足 403
2004 ACCOUNT_DISABLED 账号已禁用 403
2005 CAPTCHA_INVALID 验证码校验失败 400

实现规则

  1. message 允许在默认文案后追加冒号细节(如 参数校验失败:pageSize 必须 ≤ 100),默认文案部分不得改写;
  2. 同一 code 的 HTTP 映射全栈一致,以本表为准;
  3. 未注册的业务码(3xxx-8xxx 未登记即用)在 CI 阶段视为违规;
  4. 标识列即稳定 key(2026-09-16 EP3-R 拍板):机器可读出口 error-codes.json(支柱 1)必含 {code, key, message} 三元组——key 是客户端按 locale 渲染本地文案的 catalog 锚点(i18n 就绪位:多语言文案 v1 不做,语言透传见 rest-conventions.md 数据表示);
  5. 各栈标识符命名对照:
标识 java GlobalErrorCode golang errcode python Code ts errorCodes
INTERNAL_ERROR INTERNAL_ERROR InternalError INTERNAL_ERROR INTERNAL_ERROR
INVALID_ARGUMENT INVALID_ARGUMENT InvalidArgument INVALID_ARGUMENT INVALID_ARGUMENT
MALFORMED_BODY MALFORMED_BODY MalformedBody MALFORMED_BODY MALFORMED_BODY
NOT_FOUND NOT_FOUND NotFound NOT_FOUND NOT_FOUND
CONFLICT CONFLICT Conflict CONFLICT CONFLICT
RATE_LIMITED RATE_LIMITED RateLimited RATE_LIMITED RATE_LIMITED
IDEMPOTENCY_CONFLICT IDEMPOTENCY_CONFLICT IdempotencyConflict IDEMPOTENCY_CONFLICT IDEMPOTENCY_CONFLICT
UPSTREAM_TIMEOUT UPSTREAM_TIMEOUT UpstreamTimeout UPSTREAM_TIMEOUT UPSTREAM_TIMEOUT
UNAVAILABLE UNAVAILABLE Unavailable UNAVAILABLE UNAVAILABLE
UNAUTHORIZED UNAUTHORIZED Unauthorized UNAUTHORIZED UNAUTHORIZED
CREDENTIALS_EXPIRED CREDENTIALS_EXPIRED CredentialsExpired CREDENTIALS_EXPIRED CREDENTIALS_EXPIRED
FORBIDDEN FORBIDDEN Forbidden FORBIDDEN FORBIDDEN
ACCOUNT_DISABLED ACCOUNT_DISABLED AccountDisabled ACCOUNT_DISABLED ACCOUNT_DISABLED
CAPTCHA_INVALID CAPTCHA_INVALID CaptchaInvalid CAPTCHA_INVALID CAPTCHA_INVALID