本文要点
- 能收到 HTTP 状态码，说明请求通常已经到达某一层服务；DNS、连接超时和 TLS 失败则应先按网络层处理。
- 401、403、404、429 和 5xx 的责任层不同，不能都归因于密钥、余额或代理。
- 中转入口可能重写错误信息，应同时记录 HTTP 状态、错误类型、请求 ID、Retry-After 和脱敏后的入口域名。
- 只对 429、连接中断和部分 5xx 等瞬时故障做有限退避；配置、权限和模型错误应先修正再发送。
- 每轮只改一个变量，并设置最大重试次数和停止条件。
先保存证据，再决定是否重试
第一次报错时先记录发生时间和时区、HTTP 状态码、错误对象中的 type 或 code、request-id、Retry-After、模型 ID、脱敏后的 Base URL 域名与路径结构。密钥只记录所属项目和最近轮换时间，不能出现在截图、日志、工单或聊天中。
如果中转后台提供请求日志，还要核对请求是否到达、实际路由到哪个上游模型、是否产生 Token 或费用、最终状态来自中转层还是上游服务。没有这些字段时，先做一次最小请求，不要通过连续刷新猜原因。
先分清网络失败、中转响应和上游响应
无法解析域名、连接超时、TLS 握手失败或连接中断，说明请求可能还没有获得有效 HTTP 响应，应先检查 DNS、端口、证书链、系统时间和代理连接。通用分层步骤可对照 代理连接失败排查清单，代理地址结构不确定时看 代理 URI 格式说明。
已经收到 4xx 或 5xx 时，不要只看客户端最后一行。对照响应头、JSON 错误类型、请求 ID 和中转日志判断错误由入口网关、模型路由还是上游服务返回。中转站把多个上游错误包装成同一段中文提示时，HTTP 状态和原始错误字段比提示标题更可靠。
401 与 403：先修认证和权限，不要自动重试
401 通常先检查 API Key 是否完整、是否被撤销或过期、认证头格式是否正确，以及密钥是否属于当前入口和项目。403 更偏向项目、组织、工作区、模型或接口权限；密钥能够被识别，不代表它有权访问当前资源。
这两类错误通常不适合原样自动重试。先在当前服务的官方文档和控制台核对认证方式、密钥状态与权限，再发送一次最小请求。API Key、Base URL 和模型字段的基础映射可查看 AI API 配置与报错排查指南。
404 与模型不存在：核对路径、版本和模型映射
404 既可能表示接口路径或资源不存在，也可能表示模型 ID 不存在、模型没有向当前项目开放，或中转入口没有建立对应模型路由。先确认客户端是否会自动追加版本路径，再核对 Base URL、API 版本、资源路径和模型 ID。
不要看到 model not found 就同时更换密钥、入口、模型和代理。先从当前服务的模型目录或受支持模型接口复制真实 ID，再确认中转后台的映射名称。只改模型后复测一次；仍失败时保存请求 ID 和入口日志，再交给对应服务支持。
429 不一定等于余额不足：先读限速和配额证据
429 可能来自每分钟请求数、输入或输出 Token、并发、每日配额、消费上限，也可能来自中转站自己的套餐或上游加速限制。先查看错误正文、Retry-After、限速剩余量、重置时间和后台用量，不要只根据“请求过多”或“余额不足”一句话判断。
确认属于瞬时限速后，按 Retry-After 等待；没有明确等待时间时采用带随机抖动的指数退避，并设置最大次数。不要多个任务同时原样重试。账单和失败请求是否计费可继续核对 AI 中转计费与请求记录指南。
5xx、超时与流式中断：只重试真正的瞬时故障
500、502、503、504 或服务过载通常先查官方状态页、中转状态和同一请求 ID 的日志。确认是临时故障后才有限重试；若固定模型、固定入口持续返回相同错误，应停止并提交请求 ID，而不是无限切换出口。
流式请求还可能在已经返回 200 后中途产生错误。此时要保存最后一个完整事件、客户端超时、已接收 Token 和连接关闭位置，再判断是服务端错误、客户端提前关闭还是中间网络中断。上下文和流式边界可参考 AI API 上下文与流式输出指南。
用五分钟最小请求建立对照组
固定同一台机器、同一客户端版本、同一个入口和同一个模型，只发送不含业务资料的最小文本请求。第一次保留原配置；第二次只修正一个已经被证据确认的变量。记录两次的时间、状态码、错误类型、请求 ID、耗时和是否计费。
最小请求成功后，再逐步加入真实上下文、流式输出或工具调用。最小请求仍失败且错误证据没有变化时应停止；继续扩大请求只会增加费用和排查噪声。需要比较官方接口与中转入口的责任边界，可查看 官方 API 与中转入口区别指南。
达到停止条件后，把脱敏证据交给正确的支持方
以下情况应停止自动重试：401/403 未修复，404 的路径或模型尚未确认，429 仍在等待窗口内，连续有限次数 5xx 没有恢复，或每次请求都产生费用但没有有效输出。支持材料至少包含时间、入口域名、模型 ID、状态码、错误类型、请求 ID、Retry-After 和最小复现步骤。
代理只影响连接路径，不能修复无效密钥、模型权限、额度或上游故障。需要稳定固定出口做合法开发与文档访问时，可以 访问 PuppyIP 官网，购买后按 PuppyIP 使用教程配置；同时遵守服务方的地区、账号、速率和使用规则。
资料来源
常见问题
AI API 返回 401，可以自动重试吗？
通常不应原样重试。先修正密钥、认证头、项目或入口对应关系，再发送一次最小请求。
429 一定说明中转站余额不足吗？
不一定。它还可能来自请求数、Token、并发、每日配额、消费上限或上游加速限制，应查看错误正文、限速头和后台用量。
模型不存在为什么有时返回 404？
模型 ID、API 版本、接口路径或中转映射不存在时都可能返回 404。先确认当前入口真实支持的模型和路径。
502、503、504 应该立即切换代理吗？
不要先切换。先查官方或中转状态、请求 ID 和日志；只有出现 DNS、连接或 TLS 证据时才转向代理网络排查。
为什么流式请求已经返回 200 仍然会报错？
流式响应可能在连接建立后由服务端发送错误事件，也可能被客户端超时或中间网络提前关闭，应保存最后事件和关闭位置。
联系客服前必须保留哪些信息？
至少保留时间、入口域名、模型 ID、状态码、错误类型、请求 ID、Retry-After、最小复现步骤和脱敏日志，绝不发送真实密钥。