从 401、404、429 到 5xx 的排错树

建议用时：25 分钟（含练习）

学习目标

能够按认证、地址、模型、配额、限流和上游故障依次定位常见 API 错误。

本节产出

一棵不暴露凭证的 API 排错树

核心知识：状态码帮助定位，不替你完成诊断

模型请求失败时，先保存最少必要的证据：时间、脱敏主机与路径、请求方法、状态码、响应内容类型、错误类别和追踪编号。不要第一时间重置所有配置，也不要将完整请求头贴给别人。错误诊断需要缩小范围，而不是不断改变多个变量，让下一次结果无法比较。

首先区分是否收到 HTTP 响应。

未收到 HTTP 响应

DNS 解析失败、连接超时和 TLS 握手失败可能发生在服务返回 HTTP 状态之前；此时不存在可供解释的 401 或 500。

收到 HTTP 响应后

再判断它来自目标 API、前置网关还是其他页面。HTML 错误页和结构化 API 错误往往提供不同线索，但不能只凭格式就绝对确定响应来自哪一层。

常见状态码可以提供排查方向。401 通常指认证缺失或无效；403 表示请求被拒绝，可能与权限或策略有关；404 可能是路径、资源或服务定义的模型不可见；429 通常与限流有关，具体服务也可能用它表达配额问题；5xx 指向服务端或上游处理故障。最终仍应阅读服务文档和错误体。

图中按是否收到响应以及错误类别选择排查分支，不要求每次都检查所有分支。例如已经明确返回缺少认证头，就先处理认证；如果连 TLS 都没有建立，就不要把时间花在改模型参数上。每次只修改一个有证据支持的因素。

建立能执行的排错表

这是一张通用方向表，不是每个 API 的精确合同。例如一个服务可能用 404 隐藏无权访问的资源，或在 429 的结构化错误中区分速率与余额。要保留原错误的脱敏分类，才能找到正确的服务文档。

最小复现要保留导致失败的条件

最小请求不是随便发一句“你好”。如果问题发生在流式工具调用中，只测试普通文本并不能复现。应去掉无关的用户材料和额外参数，同时保留接口、认证方式、调用模式以及导致错误的结构。示例输入尽量虚构，并确认不会执行外部动作。

对于可以重试的暂时故障，使用有限次数、等待和随机抖动，按服务给出的等待建议处理。若接口没有明确幂等保证，不能因为网络超时就断定服务没有完成操作。请求可能已经被执行，只是响应未返回，下一步应查询状态或使用业务幂等标识。

案例：一份有顺序的故障记录

虚构客户端访问 /v1/v1/responses，得到 HTML 404。你先检查 SDK 地址拼接，发现基础地址重复包含版本前缀。修正后，返回 JSON 401，说明现在遇到的故障发生在另一个可观察阶段；继续检查认证头，发现使用了教学占位符。

第二个错误出现不意味着第一个修复无效，也不能证明整个链路已经正确。记录应写：“重复路径已移除；现收到认证错误；尚未完成有效凭证调用。”如果当前任务只是阅读练习，到这里即可停止，不需要为了看到 200 去寻找他人的密钥。

在真实获准环境中，接下来通过受保护配置使用自己的有效凭证，验证最小请求。成功后，再恢复应用的真实调用模式，确认流式解析、工具参数或输出字段没有新的问题。整个过程保留清晰的前后对照。

动手练习

1. 对三个虚构错误分类：TLS 握手失败、JSON 401、带 Retry-After 的 429。分别写出下一步应收集什么证据。
2. 为“普通聊天正常、流式工具调用失败”设计最小复现说明，保留必要条件，去除私人内容。
3. 写一份四行排错记录：现象、证据、单一改动、复核结果。未完成项明确标注。

参考答案与推演

展开

完成检查

• 能区分传输层失败与已经收到的 HTTP 错误。
• 每次改动都有证据依据，避免同时更换多个变量。
• 重试有限且考虑幂等性，不用重试解决权限问题。
• 记录可供他人复核，且没有密钥或私人请求正文。

参考与来源

• MDN：HTTP response status codes：查看状态码的通用语义。
• DeepSeek：Error Codes：比较一个具体模型服务的错误解释。