用 AI 写邮件本来是个小功能，但真接进系统后，报错往往出在想不到的地方：鉴权失败、限流被拒、返回切成半截、模型不肯按格式输出。这篇不解释协议原理，只给一套从现象到原因的排查顺序，以及超时、重试、降级、日志该怎么配，让你在半小时内把问题范围缩小到某一层。
用 AI 写邮件这个功能本身不复杂，难的是它上线之后冒出来的报错。请求发出去超时、被接口挡回来、返回了半截正文、该是结构化数据却给了一段散文，这些现象看起来都叫「报错」，实际上分属完全不同的层。不先把现象分档，上去就改代码，通常是把提示词改了十遍，问题还在原地。
下面这套顺序不讲协议，只讲怎么在半小时内把范围缩小到某一层，然后做对应的动作。邮件场景有几个特殊之处：输入往往不长但输出要求长而完整，格式约束多（收件人、称呼、正文、落款），还得考虑重试和降级。这些特点会让通用排查法失效，得单独处理。
先把报错按现象分档，别一上来就改代码
分档的意义在于：不同的档位对应不同的排查工具和不同的责任人。网络层的问题改业务代码没用，参数层的问题换通道也没用。先归好类，再动手。
| 现象 | 优先怀疑 | 第一步动作 |
|---|---|---|
| 连不上：超时、连接被拒 | 网络出口、代理、Base URL、端口 | 到 /tools/speed-test 量延迟基线 |
| 被拒：401/403/429 | Key 拼写、鉴权头、权限、限流 | 确认状态码后再看对应章节 |
| 回得来但内容不对 | 提示词、输出解析、长度截断 | 打原始返回，看是格式还是空值 |
| 时好时坏偶发 | 限流抖动、并发过高、上游不稳 | 加日志看失败样本是否同源 |
- 连不上优先怀疑网络出口、代理、Base URL 拼写和目标端口，先用站内测速页面量一下延迟基线，确认是不是纯慢而不是断
- 被拒类直接看 HTTP 状态码，401 多半是 Key 或鉴权头写错，403 常是权限或地域限制，429 是限流，别把三者混成一件事处理
- 回得来但内容不对，问题通常在提示词和输出解析，不一定是接口坏了，先别急着换通道
- 偶发失败先看时间分布：集中在某个时段多半是限流，散落各处多半是上游波动
请求层：邮件场景最容易踩的三个参数坑
邮件生成长文本的特性，会让一些在聊天场景里没暴露过的参数问题集中爆发。下面三个坑几乎每个接邮件的团队都踩过。
- 超时设太短
- 邮件往往要生成长文本，默认超时在长输出下很容易被掐断，连接、读取、整体三类超时该分档配
- 输出长度没留够
- 写邮件正文加签名，token 消耗比聊天大，长度上限给少了就是半句话结尾
- 流式和整体返回混用
- 一边要求流式一边做整段解析，就等着解析报错，二者选一种即可
还有一个容易被忽略的点：把邮件正文塞进 system 提示。system 通常对长度和字符有更严的校验，邮件里带特殊字符或长段落时，很容易触发参数校验失败，表现却是「接口报错」，其实错在自己拼请求。遇到这类报错，先把大段文本挪到 user 角色里试一次。
输出层：格式解析报错和截断怎么处理
邮件对格式的要求比聊天高：收件人、称呼、正文、落款得各就各位，还要能被下游系统解析。这让输出层成为报错重灾区。判断顺序是：先区分是「格式不对」还是「内容没返回完」。
- 打原始返回解析报错时第一件事是把原始字符串完整打出来，不要只打异常信息。看是多了 markdown 代码块，还是字段名不一致，还是压根没返回完
- 做一次清洗邮件里的换行、引号、中文标点是最常见的转义杀手，解析前先做一次清洗，别直接丢进 JSON 解析器
- 加校验加重试对必须成形的场景，加一层字段校验，失败就重试一次并收紧提示词。这比反复调提示词更快见效
- 判断是否截断如果原始返回结尾是半句话，说明是长度上限问题，回到请求层调大输出长度，而不是改解析代码
需要结构化输出的具体写法，站内已经有一篇讲透了，这里不重复造轮子。你只需要记住：让模型返回 JSON 就必须写清字段名和类型，只在提示里说「返回结构化数据」几乎注定失败。
超时、重试与降级的落地配置
这三个词经常被当成一个动作，其实是三件事。重试解决偶发，超时解决等待体验，降级解决上游整体不可用。分开配，才不会互相掩盖故障。
| 错误类型 | 是否重试 | 建议做法 |
|---|---|---|
| 超时 | 可以 | 退避加抖动，设上限 |
| 429 限流 | 可以 | 退避重试并降低并发 |
| 5xx 服务端 | 可以 | 退避重试，超过上限走降级 |
| 401/403 | 不要 | 直接修鉴权或权限 |
| 参数校验失败 | 不要 | 改请求，重试只会烧额度 |
- 重试只对可重试错误做，超时、限流、5xx 可以退避重试，401/403 和参数错误重试一万次也没用
- 重试要设上限并加抖动，批量写邮件的场景一定要限制并发，否则一限流就雪崩
- 降级链路至少想清楚一条：换备用模型、换备用通道、或者退化成模板拼装，三条里留一条能出东西
- 别把重试做成同步阻塞，用户等不起，异步队列加状态回调更适合批量邮件
什么情况下这套做法不适用：对实时性要求极高的场景，异步降级不合适，用户要的是即时返回，这时候宁可提前限流也不要把请求排进队列。另外，如果业务本身允许邮件晚几分钟发，那异步方案反而是加分项。
日志与自查清单：下次出问题能五分钟定位
排查速度取决于日志粒度。邮件场景不需要记全量请求体，但下面几个字段缺一不可，少了任何一个，下次出问题你都得重新猜。
- 每次调用至少记：时间、模型、耗时、状态码、输入长度、输出长度、是否重试、请求 ID
- 每周挑几条失败样本回放，看是同一类错误重复出现还是零散偶发，前者改配置，后者加兜底
- 上线前跑一遍小样例集：短邮件、长邮件、带附件说明的邮件、中文和英文各来一条，能覆盖大部分格式坑
- 把「什么情况下这套做法不适用」也写进文档，比如对实时性要求高的场景，异步降级就不合适
日志之外，还有一层成本视角值得定期看一眼：失败重试会放大调用量，偶发错误如果没被抓住，月底账单上会体现成看不清来源的增量。具体数字到 /price-watch 核对当时的记录，比事后猜靠谱。通道本身稳不稳，可以到 /sites 看对应站点的可信度检测结果再决定要不要换。
下一步把上面这张分档表存下来，下次报错先对号入座，再按对应章节动手。想确认当前走的是哪条通道、稳定性如何，去站内导航页对照一下当时的检测数据。→常见问题
报错提示鉴权失败，但 Key 明明是新申请的，怎么办？
先确认 Key 是不是被截断、有没有多复制空格或换行，再确认请求头字段名和前缀写对了。带中转站时还要看通道有没有开权限。可以到站内中转站目录挑一家换个通道做对照测试，如果换通道就通，问题在中转侧，不在你的代码。
邮件生成到一半就断了，返回内容不完整，是哪里出问题？
多数是输出长度上限或者超时卡住。先把最大输出调大，再把超时按生成长文本的标准放宽，并且不要在返回没结束时提前做解析。如果用的是流式，要确认客户端能正确处理分块数据，别把中间片段当完整结果用。
偶发失败要不要加重试？加几次合适？
可以加，但只对超时、限流和 5xx 这类可重试错误生效，并且一定要设次数上限和退避等待，别做成无脑循环。批量任务还要同时限制并发，否则重试本身就会把限流触发得更频繁。判断标准很简单：重试能让成功率明显上升就留，没变化就撤。
