API错误契约设计Skill：让调用方"程序化"地处理错误，而不是去解析中文提示
核心结论速览：
- 它是什么：
api-error-contract（API错误契约设计Skill）是一个把"错误"当成接口契约一部分来设计的能力包，输出的是错误分类体系、统一响应结构、HTTP 状态码映射、重试语义、多语言提示方案与错误码治理规则。 - 它解决什么：各服务错误格式五花八门、SDK 无法统一处理、调用方不知道能不能重试、终端用户看到的是一堆英文堆栈——这些"错误处理的老大难"问题，它用一套固定工作流给出可落地的规范。
- 它怎么用：输入接口清单、业务错误场景、调用方类型和兼容要求，技能按"六步工作流"依次产出分类、结构、映射、重试、多语言、治理，并附检查清单与输出模板。
- 它适合谁：开放平台与 API 网关的设计者、SDK 维护者、需要做前后端联调的前后端团队，以及任何要对外提供稳定接口的产品线。
- 它的差异点：不只给一张错误码表，而是先把"可重试判定、幂等要求、用户提示分离、错误码版本化治理"一并讲清楚，避免出现"所有错误都返回 200"这类反模式。
1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？
技能基本信息
| 项目 | 内容 |
|---|---|
| 中文名 | API错误契约设计Skill |
| 英文名 | api-error-contract |
| 技能ID | 2119813150252105730 |
| 技能类型 | 规范设计类 / 后端接口与 SDK 工程 |
| 关键词 | 错误码、错误响应、HTTP状态码、重试、幂等、可观测、用户提示、错误分类、API规范、开放平台、SDK、错误处理、限流、鉴权失败、参数校验 |
它到底解决什么问题？
在真实项目里，"错误处理"往往是最容易被忽略的一环：A 服务返回 {"errno": 1001}，B 服务返回 {"success": false, "msg": "系统繁忙"}，C 服务干脆全部返回 HTTP 200 靠业务码区分。结果是调用方（尤其是第三方和 SDK）无法用代码判断错误类型，只能去匹配中文字符串；限流了不知道要不要退避，超时了不知道该不该重试；排查线上问题时又没有 request_id 可以串起来。
API错误契约设计Skill 要做的，就是把"错误"提升为接口契约的一等公民：让调用方能够"程序化地"处理错误，而不是解析中文提示。
需要特别说明它的适用边界：该技能明确不适用于"内部函数异常设计"和"日志告警规则"，这两块请交给对应的编码规范与可观测性方案。
如何"一键安装"这类 AI 技能来提升开发效率？
这里的"安装"不是传统意义上的装软件，而是把技能接入你常用的 AI 编程助手 / 技能市场，让它在对话里被自动识别调用。通用思路如下（具体命令、入口与名称请以你所使用的技能平台官方说明为准，本技能详情中未提供具体的安装命令与下载链接）：
- 确认前提：你使用的 AI 客户端或 IDE 插件支持"技能（Skill）/ 插件"机制，并且已登录可用账号。
- 找到技能入口：在技能市场或插件面板中搜索英文名
api-error-contract，或直接用技能ID2119813150252105730定位。 - 安装 / 启用：点击安装或启用按钮，等待技能加载完成；若平台支持本地技能目录，也可按平台文档把技能包放入指定目录。
- 验证是否生效：新建一个会话，输入类似"帮我设计一套订单服务的 API 错误码与错误响应结构，要求支持重试判定和字段级校验"的问题，观察返回内容是否包含错误分类 + 错误码表 + 响应示例 + 治理建议这套结构。如果能稳定输出这一套，说明技能已正常挂载。
- 注意按需触发：该技能是按"任务场景"触发的——描述里写明它用于"需要设计或统一 API 错误码、错误响应结构与重试语义时"，所以提问时把场景讲清楚（新 API、格式不统一、调用方不知是否重试、要给终端用户提示），命中率会更高。
2. 该技能的主要功能和特点
- 错误分层分类体系：把错误拆成三大类——客户端错误（参数、认证、权限、资源状态、限流）、服务端错误（内部异常、依赖失败、超时、容量不足）、业务错误（余额不足、库存不足、状态不允许）。分类清晰，后续的状态码映射、重试判定才有依据。
- 统一错误响应结构：给出包含
code、message、request_id、details、retryable、doc_url的标准结构，并对每个字段提出硬性要求（如code需稳定、机器可读、全大写下划线、不带变量）。 - HTTP 状态码映射表：内置从 400/401/403/404/405/409/422 到 429、500、502/503、504 的完整映射，避免团队在"语义错误该用 400 还是 422"上反复拉扯。
- 重试语义设计：明确
retryable字段与建议退避策略；429 与 503 需返回Retry-After；只有幂等接口才允许自动重试，非幂等接口要求调用方带幂等键；超时不能简单判定为失败，需用查询接口兜底。 - 多语言与用户提示分离：错误码与展示文案解耦，客户端按
code映射本地化文案，不直接展示服务端message；并强制要求响应中不得出现堆栈、SQL、内部路径等敏感信息。 - 错误码治理机制：错误码目录集中管理、新增需评审、废弃码保留映射并标注替代、统计各码频率以识别设计缺陷、SDK 依据目录自动生成异常类型。
- 开箱即用的检查清单与输出模板：10 项检查清单（每个错误都有稳定 code、状态码与类别一致、含 request_id、retryable 明确、幂等要求入文档、字段级错误用 details 数组、无内部细节泄露、提示分离、目录版本化、有文档链接与示例），以及现成的 Markdown 输出模板。
- 明确的反模式清单：直接点名"全部返回 200"“返回异常堆栈”“message 拼变量导致客户端无法匹配”“所有错误都标可重试”"限流不返回 Retry-After"这五种典型坑，评审时可当红线用。
和普通做法比强在哪？ 普通的"接口文档里写一段错误说明"，只能覆盖"有哪些错误码"；而这个技能把分类 → 结构 → 状态码 → 重试 → 多语言 → 治理六个层面串成一条闭环，产出的是一份能被 SDK 直接消费、能被网关统一拦截、能被前端统一映射的契约。
3. 如何使用该技能？
整体是一条"先给输入、再走六步、最后套模板出稿"的路径。
第 0 步：准备四类输入
据技能详情，调用前最好准备好：
- 接口清单与业务错误场景（例如"下单接口：库存不足、余额不足、地址非法、重复提交"）；
- 调用方类型（内部服务 / 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"
}
第 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 依据目录自动生成异常类型。
输入示例（可直接参考的问法）
“我们是一个电商开放平台，需要给第三方开发者提供订单相关 API。请帮我设计错误契约：1）接口包括创建订单、查询订单、取消订单；2）调用方是第三方 SDK；3）已有旧错误码
E1001（参数错误）需要保留兼容；4）需要支持中英文提示。请输出错误分类、错误码表、响应示例和治理建议。”
输出说明
技能会按内置的 Markdown 模板产出四块内容：错误分类（类别 / 前缀 / 状态码 / 可重试）、错误码表（code / HTTP / 含义 / 触发条件 / 处理建议）、响应示例、治理（新增流程 / 废弃流程 / 监控指标）。拿到后可直接贴进接口文档或评审稿，再用那 10 条检查清单逐项打勾验收。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| api-error-contract（API错误契约设计Skill） | 面向 AI 助手的错误契约设计顾问 | 错误分层分类、统一响应结构、状态码映射、重试语义、多语言提示、错误码治理、检查清单与输出模板 | 低：在支持技能的 AI 客户端中启用即可；无需自建规范体系，提问即可产出初稿 | 新 API 设计、多服务错误格式统一、SDK 异常体系设计、前后端联调 | 优势：覆盖"结构+重试+治理"全链路，且内置反模式提醒；不足：产出仍需结合团队实际评审落地，不含具体代码实现 |
| OpenAPI / Swagger 规范文档 | 接口描述标准 | 描述接口路径、参数、响应结构，可生成文档与部分客户端代码 | 中：需要编写与维护 YAML/JSON，错误部分通常只能描述结构，无法表达"是否可重试"这类语义 | 接口文档化、代码生成 | 优势：生态成熟、工具链丰富；不足：对错误码分类、重试语义、治理流程几乎不提供方法论，需要团队自己补规范 |
| RFC 7807 Problem Details 等通用错误格式标准 | 通用错误载荷格式约定 | 定义一套标准的错误响应字段（类型、标题、状态、详情等） | 中：需要团队自行翻译为内部规范并推动各服务改造 | 希望与国际通用格式对齐的对外 API | 优势：标准化程度高、跨团队认知成本低；不足：不涉及错误码目录治理、多语言提示策略与幂等重试细则 |
| 公司内部 API 规范 Wiki / 设计评审制度 | 组织级流程约束 | 通过文档 + 评审保证一致性 | 高：依赖人工维护与推动，容易随人员变动而失效 | 有专职架构团队的中大型组织 | 优势：贴合业务、约束力强；不足：沉淀慢、更新滞后，新人上手成本高，缺少可复用的检查清单 |
一句话选型建议：如果你缺的是"从零到一份能评审的错误契约初稿"，用本技能最快；如果你缺的是"接口描述文件"，OpenAPI 更合适；如果你要和國際标准对齐，可把通用错误格式标准与本技能的分类、重试、治理部分组合使用。
5. 该技能的典型应用场景与实际体验情况
场景一：开放平台对外 API 首次定型
角色：开放平台后端负责人。痛点：第一批第三方接入方上线后，纷纷来问"这个报错是什么意思"“要不要重试”，客服成本极高。使用方式：把接口清单和业务错误场景喂给技能，先产出错误分类与错误码表，再确认"业务错误用 200 还是 4xx"这个全局口径。实际体验：上手几乎零门槛，提问一次就能拿到表格化初稿；效果最明显的是 retryable 和 doc_url 两个字段——过去从没想过要写进响应里，加上之后调用方的咨询量显著下降。注意点是错误码前缀要提前规划，否则后期容易重名。
场景二：微服务网关统一错误出口 角色：基础架构 / 网关团队。痛点：十几个服务各自返回不同结构，前端没法写统一的错误拦截器。使用方式：让技能先输出统一响应结构，再按"客户端错误 / 服务端错误"两类分别做网关层归一化。实际体验：技能的"反模式"清单在这里特别好用，可以直接当评审红线——"所有错误都返回 200""直接返回堆栈"这两条几乎每个老系统都能对上号。需要注意的是改造要分阶段，技能给的检查清单可以当作灰度上线的验收表。
场景三：SDK 异常体系设计
角色：SDK 维护者。痛点：SDK 只能抛一个泛化的异常，调用方无法按类型捕获。使用方式：用技能产出的错误码目录作为输入，让 SDK 根据目录自动生成异常类型。实际体验：这是最能体现"契约"价值的一环——一旦 code 稳定且全大写下划线、不带变量，代码生成就是水到渠成的事。注意 code 一旦对外发布就不能随意改名，必须走废弃映射流程。
场景四：前后端联调与终端用户提示
角色：前端工程师与产品经理。痛点：服务端 message 直接弹给用户，出现"NullPointerException"这种尴尬画面。使用方式：按技能建议，客户端只认 code，本地化文案由前端按 code 映射，服务端 message 只给开发者看。实际体验：分离之后前端多了一张映射表要维护，但换来的是多语言和文案改版完全不依赖后端发版；details 数组也让表单字段级报错变得非常自然。注意敏感信息过滤要真的做，不能只在文档里写。
6. 该技能能为用户带来的价值
- 把"事后救火"变成"事前定型"：错误契约在设计阶段一次性想清楚，避免上线后被第三方追问"这个码什么意思"“要不要重试”，减少大量重复沟通。
- 显著降低联调成本：统一的结构 + 稳定的
code+ 明确的retryable，让前端拦截器、SDK 异常、网关归一化都能一次写对，而不是每个接口写一遍 if-else。 - 降低接入门槛：第三方开发者拿到
doc_url和字段级details，能自助定位问题；多语言场景下客户端只需维护一张code → 文案映射表。 - 可量化收益点：可统计的指标包括——各错误码出现频率（用于识别设计缺陷）、因错误理解导致的工单数量、SDK 异常类型的覆盖度、限流场景下因
Retry-After减少的重试风暴。 - 长期价值在于治理：错误码目录版本化、新增需评审、废弃码保留映射，让错误体系能随业务演进而不腐化；检查清单与反模式清单可作为团队长期沿用的评审基线。
- 安全与合规收益：强制"不泄露堆栈、SQL、内部路径"，从规范层面堵住一类常见的信息泄露风险。
7. 常见问题 FAQ
Q1：这个技能怎么安装？我找不到具体的安装命令怎么办？
A：它属于 AI 技能（Skill）形态，不是独立安装的软件。通用路径是：在支持技能机制的 AI 客户端 / IDE 插件中打开技能市场，搜索英文名 api-error-contract 或技能ID 2119813150252105730，启用后在对话中描述"需要设计 API 错误码与错误响应结构"即可触发。具体命令、入口位置与支持的平台范围，以你所使用平台的官方说明为准。
Q2：它是收费的吗？ A：本技能详情中未提供任何定价信息，是否收费取决于你所在技能平台的计费策略，请以官方说明为准。
Q3：它适合谁用？我是小团队也需要吗？ A：最适合开放平台、微服务网关、SDK 设计与前后端联调相关角色。小团队同样值得用——错误契约的成本主要在设计阶段，越早定型越省事；而且技能输出的检查清单可以直接当轻量评审表用，不需要专职架构师。如果你只有一两个内部接口且不对外，优先级可以放低。
Q4：它和 OpenAPI 文档是什么关系？会不会重复劳动？ A：不冲突。OpenAPI 解决"接口长什么样"，本技能解决"出错时怎么约定"。实践中常见做法是：先用技能把错误分类、错误码表、重试语义定清楚，再把结果写进 OpenAPI 的错误响应定义里，两者互为补充。
Q5：技能产出的错误码表能直接用吗？
A：可以当高质量初稿，但建议做三件事再落地：一是确认"业务错误用 200 + 业务码还是 4xx"的全局口径；二是检查 code 命名是否符合团队前缀规划、是否与历史码冲突；三是按那 10 条检查清单逐项验收（尤其是 request_id、retryable、幂等要求写入文档、无内部细节泄露这几条）。