名称

api-error-contract

描述

当需要设计或统一 API 错误码、错误响应结构与重试语义时使用。该技能建立错误分类体系、HTTP 状态码映射、可重试判定、用户提示与幂等要求，并给出多语言错误目录与版本兼容规则。适用于开放平台、微服务网关、SDK 设计与前后端联调。关键词：错误码、错误响应、HTTP状态码、重试、幂等、可观测、用户提示、错误分类、API规范、开放平台、SDK、错误处理、限流、鉴权失败、参数校验。

API 错误契约设计

让调用方能够“程序化地”处理错误，而不是解析中文提示。

何时使用

新 API 需要定义错误响应。
各服务错误格式不一致，SDK 无法统一处理。
调用方无法判断是否该重试。
需要给终端用户展示可理解的提示。

不适用：内部函数异常设计；日志告警规则。

输入

接口清单与业务错误场景。
调用方类型：内部服务、SDK、第三方。
现有错误码与兼容要求。
多语言要求。

工作流

第 1 步：分层分类

按 references/error-code-taxonomy.md 分为：

客户端错误：参数、认证、权限、资源状态、限流。
服务端错误：内部异常、依赖失败、超时、容量不足。
业务错误：余额不足、库存不足、状态不允许。

业务错误用 200 + 业务码还是 4xx，需全局统一，不能混用。

第 2 步：定义响应结构

{
  "code": "PAYMENT_CARD_EXPIRED",
  "message": "银行卡已过期，请更换支付方式",
  "request_id": "req_01H...",
  "details": [{"field": "card.expiry", "reason": "expired"}],
  "retryable": false,
  "doc_url": "https://docs.example.com/errors/PAYMENT_CARD_EXPIRED"
}

要求：

code 稳定、机器可读、全大写下划线，不带变量。
message 面向开发者，可本地化。
request_id 必带，便于排查。
details 用于字段级校验错误。
retryable 明确是否可重试。
doc_url 指向错误说明。

第 3 步：HTTP 状态码映射

场景	状态码
参数校验失败	400
未认证	401
无权限	403
资源不存在	404
方法不允许	405
冲突/状态不允许	409
语义错误	422
限流	429
内部错误	500
依赖不可用	502/503
超时	504

第 4 步：重试语义

明确 retryable 与建议退避。
429 与 503 提供 Retry-After。
幂等接口才允许自动重试；非幂等需调用方带幂等键。
超时不能简单判定失败，可能已成功，需查询接口兜底。

第 5 步：多语言与用户提示

错误码与展示文案分离。
客户端按 code 映射本地化文案，不直接展示服务端 message。
敏感信息（堆栈、SQL、内部路径）不得出现在响应中。

第 6 步：治理

错误码目录集中管理，新增需评审。
废弃码保留映射并标注替代。
统计各错误码频率，识别设计缺陷。
SDK 根据目录自动生成异常类型。

检查清单

[ ] 每个错误都有稳定 code。
[ ] HTTP 状态码与错误类别一致。
[ ] 响应包含 request_id。
[ ] retryable 字段与退避建议明确。
[ ] 幂等要求已写入文档。
[ ] 字段级错误使用 details 数组。
[ ] 无内部实现细节泄露。
[ ] 用户提示与开发者信息分离。
[ ] 错误码目录已版本化。
[ ] 有文档链接与示例。

输出模板

## 错误分类
| 类别 | 前缀 | 状态码 | 可重试 |
| --- | --- | --- | --- |

## 错误码表
| code | HTTP | 含义 | 触发条件 | 处理建议 |
| --- | --- | --- | --- | --- |

## 响应示例
...

## 治理
- 新增流程 / 废弃流程 / 监控指标

反模式

所有错误都返回 200，靠业务码区分。
直接返回异常堆栈。
message 里拼接变量，客户端无法匹配。
所有错误都标记可重试。
限流不返回 Retry-After。

参考文件

references/error-code-taxonomy.md：错误码命名与分类细则。