运行与帮助
错误与重试
先根据状态、错误体和响应阶段判断失败类型，再决定修正请求、等待额度恢复还是进行次数受限的重试。
错误响应结构
网关自身、兼容协议和异步任务可能使用不同 envelope。客户端应同时保留 HTTP 状态、完整错误体和响应头，不要只解析一个固定路径。
| 来源 | 常见结构 | 读取方式 |
|---|---|---|
| 网关前置校验 | {"code":"API_KEY_REQUIRED","message":"..."} | 读取顶层 code 与 message |
| OpenAI 兼容或上游错误 | {"error":{"type":"...","message":"..."}} | 读取 error，同时保留未知字段 |
| 失败的异步图片任务 | {"status":"failed","http_status":502,"error":{...}} | 轮询 HTTP 200 时仍要检查任务 status |
状态码与建议动作
| 结果 | 常见原因 | 默认动作 | 自动重试 |
|---|---|---|---|
400 / 422 | JSON、字段、协议或模型能力不匹配 | 修正请求 | 否 |
401 | Key 缺失、格式错误、无效或撤销 | 修正认证 | 否 |
403 | 分组、模型、订阅、账户或来源权限不足 | 修正权限 | 否 |
404 | 路径错误、功能未开放或资源不存在 | 核对 endpoint 和功能状态 | 通常否 |
413 | 请求体超过当前网关上限 | 缩短历史或减小附件 | 否 |
429 | 速率、并发、Token、余额或额度限制 | 读取错误代码和 Retry-After | 仅临时限流可重试 |
5xx 或提供方过载 | 网关、网络或模型服务暂时失败 | 保留请求 ID，有限退避 | 条件允许 |
2xx 后流中断 | SSE 已建立后出现上游错误或断线 | 检查最后事件与副作用 | 不能盲目重放 |
429 不能只按状态码处理：余额和总额度不足不会因为等待几秒恢复，速率或临时过载才适合遵循 Retry-After 或指数退避。
流式错误
开始流式输出后，HTTP 状态通常已经是 200，后续失败只能作为 SSE 事件或连接中断出现。客户端应：
- 分别处理协议的完成、失败、不完整和
error事件。 - 保留已经收到的内容，但不要把断流当作完整成功。
- 区分客户端取消、读取超时、代理断开和服务端错误。
- 工具或其他有副作用的操作执行后，先核对结果再决定是否重试。
重试策略
- 只重试确认属于临时故障且业务允许重放的请求。
- 优先遵循有效的
Retry-After；否则使用带随机抖动的指数退避。 - 设置较小的最大尝试次数和总体截止时间，不让 SDK 与业务层同时无限重试。
- 每次尝试记录请求时间、模型、协议、HTTP 状态、错误代码和服务端返回的请求 ID。
- 对发信、支付、写文件和外部工具调用使用业务幂等键或执行去重。
请求 ID
排错时记录响应头实际返回的 X-Request-Id 和 X-Client-Request-Id（如果存在）。当前不承诺服务会原样保留客户端主动发送的 X-Client-Request-ID，因此不要把自定义值作为唯一关联键。
请求 ID 不应包含 Key、Prompt、完整响应或个人信息。SDK 不暴露 headers 时，保留控制台对应记录标识。
需要支持时提供的信息
- UTC 时间和本地时区，精确到分钟。
- 最终请求 URL、协议、模型 ID、Key 所属分组和 SDK/客户端版本。
- HTTP 状态、错误代码、经过脱敏的完整错误体和响应请求 ID。
- 流式请求最后收到的事件类型，以及是否已有文本或工具执行。
不要提供完整 API Key、未脱敏 Prompt、完整私有文件或账户密码。