排障指南
高效排障的目标不是多试几次，而是用最少的变量变化确定问题发生在哪一层。
第一步描述现象记录接口、时间、状态码与页面表现
第二步收集证据关联请求 ID、Key、模型、任务和用量
第三步采取动作修正配置、等待恢复或有限重试
- 地址与鉴权
- 先排除基础配置问题
- 模型与参数
- 确认资源和请求有效
- 额度与限流
- 区分预算和请求节奏
- 任务与服务
- 判断等待、失败或异常
日志中不要记录完整 API Key。提供排障信息时使用 Key 名称或可识别前缀，并对业务输入、输出和用户数据做必要脱敏。
先保存一份问题现场
按症状选择第一动作
四条常见排障路径
地址或鉴权失败
确认 Base URL 为 https://api.ggpu.ai，后面直接拼接接口路径。检查请求头是否为 Authorization: Bearer <完整密钥>，以及 Key 是否启用、过期或触达独立额度。
模型或参数失败
从 GET /v1/models 获取当前账号可用的准确模型 ID。将请求缩减为最小字段；基础请求成功后，再逐项恢复温度、长度、图片尺寸或其他参数。
超时、卡住或任务未完成
先判断请求是同步响应、流式连接还是异步任务。客户端超时不代表平台停止执行；如已获得任务 ID，应查询任务而不是重新创建。
额度、限流或临时服务异常
额度问题先调整预算或 Key 配置；429 先降低请求节奏；临时 5xx 可以有限重试。每次尝试都要单独记录，避免请求风暴。
用最小对照实验缩小范围
一次只改变一个变量：
- 固定 Base URL、Key 和模型，只把消息缩短。
- 固定请求体，将第三方客户端换成最小 curl。
- 固定单请求，先关闭自动重试和批量并发。
- 固定客户端，把同步与流式路径分开验证。
- 固定任务 ID，只查询状态，不重复创建任务。
如果最小 curl 成功而业务客户端失败，问题更可能在客户端路径、超时、流式解析或重试；如果两者都失败，再回到平台配置与状态层。
什么时候停止重试
- 状态码明确表示参数、鉴权、权限或资源错误
- 已达到客户端最大重试次数
- 流式请求已经展示部分内容，重试会造成重复结果
- 异步创建请求可能已成功，但尚未确认任务是否存在
- 同类请求持续失败，需要先保存现场并检查平台状态