错误码表还在靠人肉硬填？先看看这些常见的翻车姿势
一、那些年我们见过的错误码文档惨案
如果你维护过一个稍微像样的 API 服务，下面这些场景大概率眼熟：
惨案一：代码先行，文档垫底。 接口上线了，错误码散落在各个 catch 块和枚举类里，文档里只写了一句「400 表示请求错误」。用户来问「40001 和 40002 有什么区别」，你打开自己的代码库搜了十分钟才敢回复。
惨案二：一次性 AI 生成，全文幻觉。 听说 AI 能写文档，于是把整个服务的描述丢给模型说「帮我生成 API 文档」。出来的东西看着很漂亮——参数齐全、格式规范，但仔细一对：user_id 写成了 userId，一个不存在的错误码 50099 混在表格中间，响应示例里的字段和真实返回对不上。用户按文档接入，当场翻车。
惨案三：文档写好了，没人更新。 上次迭代改了错误码语义，文档还是三个月前的版本。用户对着旧文档排查了半天，最后在群里发了一句「你们文档和实际返回不一致」，你的脸有点挂不住。
这些问题的共性是：把 AI 当成了替代思考的生成器，而不是一条有输入约束的处理流水线。 下面讲讲怎么把这条路走对。
二、用户的真实痛点在哪
独立开发者和小团队在 API 文档这件事上的痛点非常具体：
- 没时间。写文档的时间成本看起来「不产生价值」，永远排在开发后面，最后就是永远不写。
- 信息源分散。错误码定义在代码里、注释里、口头约定里，甚至只在某个人的脑子里。
- 格式不统一。今天写的文档和上个月的文档，字段顺序、命名风格、错误码分组逻辑都不一样，用户读起来费劲。
- 更新跟不上。文档一旦和代码脱节，比没有文档更糟——它会误导用户。
而 AI 恰好擅长处理这类「机械但费神」的工作：只要给它结构化的输入（代码、注释、错误码枚举），它输出的速度和一致性远超人肉整理。前提是——你得喂对了东西。
三、正确的使用流程
第一步：先收敛信息源，再谈生成。
不要指望 AI 凭空理解你的服务。先把真实的错误码枚举类、接口的请求/响应结构体、关键注释整理出来。哪怕就是三段代码粘贴，也比一段「我的服务是一个用户管理服务」的描述强十倍。AI 不创造信息，只整理信息——这是避免幻觉的第一道闸门。
第二步：用带约束的提示词，而不是一句「帮我写文档」。
明确告诉 AI：只能使用我提供的错误码，不得新增、不得猜测；输出格式固定；每个错误码必须包含触发场景和处理建议。可以在提示词里要求它「对找不到的信息标注 TODO，而不是自行补全」——这一招能把幻觉率压到很低。
第三步：人工做一次抽查，而不是通读。
生成的文档不需要逐字审。抽查三处高风险点：错误码数量是否和枚举对得上、参数类型是否和结构体一致、响应示例能否通过你本地的请求复现。抽查通过，基本可以放心发布。
第四步：把流程固化。
把提示词存成模板，每次迭代后重新跑一遍。文档更新从「想起来才做」变成「改完代码顺手跑一次」，这是流程上最关键的转变。
下面是一个可直接复制的提示词模板：
你是一位资深 API 文档工程师。请根据我提供的代码材料，生成 API 文档和错误码说明。
【硬性规则】
1. 只能使用我提供的错误码、字段名、参数，严禁新增、改名或猜测任何内容。
2. 如果信息缺失，在对应位置写【TODO：待补充】，不要自行补全。
3. 错误码总数必须与我提供的枚举数量一致，输出前先数一遍。
【输出格式】
## 一、接口说明
- 接口名称 / 请求方法 / 路径
- 请求参数表格（参数名、类型、必填、说明）
- 响应示例（基于我提供的结构体生成 JSON）
## 二、错误码说明
表格包含五列：错误码、HTTP 状态码、含义、常见触发场景、用户处理建议
## 三、接入注意事项
列出 2-4 条我从注释中提取的真实注意点，没有则写「无」
【我的代码材料如下】
（在此粘贴错误码枚举、接口结构体、相关注释）四、用 AI 前后对比
| 维度 | 之前（人肉硬写） | 之后（流程化 + AI） |
|---|---|---|
| 首次产出 | 拖延数天甚至不写 | 材料备好后几分钟出初稿 |
| 格式一致性 | 前后风格漂移 | 模板固定，风格稳定 |
| 错误码说明 | 只有一列「含义」 | 含触发场景 + 处理建议 |
| 迭代更新 | 改代码不改文档 | 顺手重跑模板，几分钟同步 |
| 用户提问量 | 群里反复解释相同问题 | 「看文档第三节」即可 |
注意对比里最值钱的不是「快」，而是一致性和可维护性——文档从一次性劳动变成可重复执行的流程，这才是小团队真正需要的。
五、几个容易踩回去的坑
- 不要让 AI「顺便」设计错误码体系。 错误码的分组和编号规则应该由你在代码里定义好，AI 只负责解释，不负责发明。
- 不要用生成的文档反向改代码。 一旦发现文档和代码冲突，先改代码材料重新生成，别让文档变成第二个事实源。
- 不同模型的表现差异是存在的，如果发现某个模型频繁幻觉，换模型或收紧提示词约束即可，工具选择上以各家官网价格页和免费额度自行评估。
写在最后
API 文档和错误码说明，本质上是一项「输入越干净、输出越可靠」的工作。把 AI 当流水线而不是许愿机，它就是小团队性价比最高的文档同事。
如果你正在寻找稳定、价格透明的模型 API 来跑这类文档流程，可以试试 ThisToken——聚合多家主流模型，一个 Key 通吃，注册入口在这里：https://api.thistoken.ai/register
---
不想折腾多家供应商的接入差异？在 https://api.thistoken.ai/register 注册，用一个 base_url 调用所有模型。