接口报错排查手册：把错误码贴给 AI 整理成表格

一句话结论

接口报错先别翻文档，把错误码连同请求上下文整段贴给 AI，让它按「现象—可能原因—下一步动作」整理成一张排查手册，十分钟内就能拿到能照着做的清单。

这篇解决什么问题

联调的时候最烦的不是报错，是同一个 401 反复出现，你翻完文档翻日志，翻完日志又去问人。这篇讲的就是把这个过程压缩：用一段结构化提示词，让 AI 把散落的错误码整理成一份有排查顺序的手册。

适用：你有完整的报错日志片段（含错误码、请求路径、时间），想让 AI 帮你归类并给出排查顺序。不适用：错误只有一句「请求失败」，没有任何错误码或响应体，这种情况 AI 也只能瞎猜。

开始前要准备什么

• 一个能贴长文本的 AI 对话工具，DeepSeek 或豆包均可，免费额度够用
• 一段真实报错日志：错误码、请求路径、响应体、发生时间，缺一不可
• 该接口的文档页或字段说明，能截图或复制文字都行
• 预计耗时：整理素材 5 分钟，对话往返 10 分钟以内

具体怎么做

第 1 步 · 把日志洗干净再贴

原始日志里混着大量无关行，直接贴进去 AI 会抓错重点。先把报错前后各十几行截出来，把 token、手机号这类敏感内容替换成占位符。

下面是一段接口调用的报错日志，我已经做了脱敏处理，token 用 XXX 代替。请你帮我做三件事：第一，列出这段日志里出现的所有错误码和对应的原始报错文本；第二，标出哪些是请求方的问题、哪些可能是服务方的问题；第三，指出你还缺哪些信息才能判断根因。日志如下：n【时间】2024-11-05 14:22:31n【请求】POST /api/v2/order/createn【状态码】401n【响应体】{“code”:10003,”message”:”signature invalid”,”requestId”:”req_XXXX”}n【上一次成功调用】13:58:02，同一接口，同一账号

预期产出：一张三列的小清单——错误码、原始报错、责任方初判，外加一句「还缺什么信息」。这一步的价值在于它常常会反问你「签名用的时间戳是多少」，而这个问题往往就是答案。

第 2 步 · 让它按模板出排查手册

第一次的回答通常偏分析，不像手册。第二轮要把格式钉死，逼它输出可以照着执行的东西。

把上面的分析整理成一份排查手册，用表格输出，四列：错误码、现象描述、最可能的三个原因（按可能性从高到低排）、对应的验证动作。验证动作要具体到「看哪里、比什么、改什么」，不要写「检查签名配置」这种笼统的话。手册针对的读者是刚接手这个接口的同事，他手上只有日志和接口文档。

预期产出：一份四列表格。好的手册里，「验证动作」这一列应该是能直接执行的句子，比如「对比本地时间戳与服务器返回的 Date 头，差值超过 5 分钟就是它」。

第 3 步 · 补上文档，让它对齐字段

光有日志，AI 不知道你们接口的字段约定。把文档里的参数说明贴进去，它给出的原因会具体很多。

这是该接口的文档节选，请结合前面的日志重新审视你列的原因。特别注意文档里对 signature 字段的说明和它对参数排序的要求。如果文档描述和日志现象有冲突，单独指出来，不要强行圆回去。文档节选如下：n【接口】/api/v2/order/createn【signature】由 appSecret 与全部请求参数按 key 字典序拼接后做 HMAC-SHA256，取十六进制小写n【timestamp】毫秒级，与服务端时间偏差不得超过 300000 毫秒

预期产出：一份修订版手册。这一步最有用的是「冲突提示」——文档说时间偏差不能超过 5 分钟，日志里上次成功是半小时前，AI 会把时间戳偏移列进高可能原因。

第 4 步 · 让它生成验证顺序

手册有了，但人的问题是不知道先查哪个。让 AI 按「最省时间的先查」重新排序。

把手册里的原因重排一次，排序原则：不需要改代码、不需要重启服务、单人或一条命令就能验证的排前面；需要找人配合或改配置的排后面。每条前面标上序号和预估耗时，最后给我一句话，说明如果第一项就命中了，我该改什么。

预期产出：一个带序号和耗时的排查路径。多数情况下排在第一的是核对时间戳，因为一条 date 命令就能验证。

第 5 步 · 收口成能存档的文档

对话里的东西过两天就找不到了。最后一步让它输出成可以直接贴进团队文档的格式。

把最终版手册整理成 Markdown，开头加一段三行的摘要说明这份手册覆盖哪个接口、基于哪次报错整理、最后更新日期。表格保留四列，排查顺序用有序列表单独列一遍。末尾加一节「本次未验证的猜测」，把还没确认的原因列出来，标明待验证。

预期产出：一份 Markdown 文档，可以直接放进仓库的 docs 目录。「本次未验证的猜测」这一节很多人会砍掉，我建议留着，下次同类报错出现时它就是第一条线索。

实测记录

有一次我只贴了错误码没贴响应体，AI 给出的三个原因全是猜的，改成贴完整响应体之后，它直接点出签名里漏了一个参与排序的字段。这个差别很明显。

最容易错的 3 个地方

1. 只贴错误码不贴上下文。同一个 401 可能是签名错、可能是 token 过期，AI 分不出来。至少给路径、响应体和上一次成功的时间。
2. 第一轮就要求出成品手册。我试过，输出会很长但很空。正确做法是先让它分析、再让它按模板整理，分两轮。
3. 把 AI 给的原因当结论直接用。它列的是可能性排序，不是诊断结果。每条后面必须跟着你自己的验证动作，没验证过的要单独标出来。

可复用的东西

五个提示词可以收成一套固定模板：洗日志、出表格、补文档、重排顺序、收口存档。前两个是核心，后三个是打磨。真正常用的其实是第二轮那个四列表格模板，换个接口也能直接套。

把你们组最常报的那三五个错误码先跑一遍，攒成一份自己的手册，比每次临时问要快得多。你手上现在卡着的那个报错，是错误码本身看不懂，还是看懂代码了但不知道先改哪？

如果你也经常要做这件事，欢迎在评论区说说你的卡点和做法；也可以留言告诉我，你想看哪个岗位的哪件活怎么用 AI 拆。

admin 普通

收藏 海报 链接