# 排障与重试

## 定位请求

保留请求时间和时区、HTTP 方法和路径、模型名称、API Key 前缀或 ID、HTTP 状态以及 `x-cr-request-id`。如果响应包含 `x-cr-usage-id`，也一并保留。每次轮询有独立的请求 ID。成功轮询返回的 usage ID 仍指向最初提交的用量记录。

请求和响应正文只保留脱敏后的必要片段。不要在工单或聊天中发送 `Authorization` Header、完整 API Key、客户输入或私有媒体 URL。

## 按阶段排查

| 现象 | 优先检查 |
| --- | --- |
| 无法连接、TLS 错误 | API Base URL、DNS、证书、代理及网络出口 |
| 400 或参数校验失败 | 必填字段、请求体和模型能力 |
| 401 | Bearer Header、完整 API Key、有效期与停用状态 |
| 403 或访问被拒绝 | API Key、团队或组织的模型访问策略，以及额度状态 |
| 404 | 接口路径、模型名称、`previous_response_id` 或任务 ID，以及所用 API Key |
| 429 或部分 5xx | 限流、并发、错误信息与有界退避 |
| SSE 中断 | 读取超时、代理缓冲、客户端取消与服务端流错误 |
| 任务长时间未结束 | 任务 ID、轮询间隔、终态处理和总体等待上限 |

## 有界重试

只对临时网络错误、429 和部分 5xx 进行有限重试。使用指数退避和随机抖动，并设置最大次数和业务截止时间。先修正认证、权限和参数错误，不要自动重试。

生成类 POST 超时不能证明任务未创建。直接重新提交可能创建重复任务并再次计费。

## 联系支持

如果问题仍未解决，向团队管理员或 CR 服务支持提供“定位请求”中的信息，并使用最小的脱敏输入复现问题。