外观
请求排障与反馈
适合已经配置好工具，但遇到报错、超时、输出中断或使用记录不匹配的用户。先定位失败发生在哪一步，再决定改配置、等待还是反馈。
先保留一次失败，再改一个变量
记录发生时间与时区、工具版本、模型、Key 名称和错误代码。先保留失败现场，再只改地址、模型或一个设置；一次改很多项，会失去判断依据。
按这三步缩小范围：
- 没有收到 HTTP 响应：先查域名解析、TLS、代理和连接超时。
- 收到 HTTP 错误：同时看状态码与错误正文，按下面的表处理。
- HTTP 200 但结果不完整：检查流式结束事件、实际图片内容和使用记录，不能只凭状态码判定完成。
HTTP 状态速查
| 现象 | 优先检查 | 下一步 |
|---|---|---|
| 400 / 参数错误 | JSON 是否有效，字段是否属于当前协议，模型是否接受这些参数 | 去掉可选参数，用同协议最小请求验证 |
| 401 | Key 是否完整，认证头和当前 Provider 是否正确 | 对照对应工具指南，不反复重试无效 Key |
| 403 | 错误正文中的过期、余额、分组权限或订阅状态 | 修正对应限制；不能只凭 403 判断 Key 错误 |
| 404 | 完整请求路径、协议、模型 ID | 区分“路径不存在”和“模型不存在”，不要随意增删 /v1 |
| 413 / 请求过大 | 原始文件、Base64 后的体积、整段会话和总请求体 | 缩小附件或上下文；大小限制不等于模型 token 上限 |
| 429 | 错误代码是额度耗尽、并发、队列还是短时限流 | 先看429 的不同原因 |
| 500 / 502 / 503 / 504 | 错误正文、发生时间、分组状态、是否已有部分结果 | 保留现场，有限重试；超时后先查记录 |
错误可能由客户端代理、站点、网关或上游返回。代码和正文比单独一个 HTTP 状态更有用；HTML 错误页也不应作为模型 JSON 解析。
429 不一定是请求太快
| 错误代码或提示 | 通常指向 | 怎么处理 |
|---|---|---|
API_KEY_QUOTA_EXHAUSTED / insufficient_quota | Key 额度已用完，或响应正文描述的额度问题 | 核对 Key 额度、账户或订阅；减慢请求不会自动恢复额度 |
USAGE_LIMIT_EXCEEDED | 订阅用量达到窗口限制 | 查看当前用量与重置时间，不持续重发 |
gateway_concurrency_limit | 同时执行的请求过多 | 减少并发，等正在执行的请求结束 |
gateway_queue_full | 等待队列已满 | 暂停提交新任务，稍后降低并发再试 |
INVALID_AUTH_RATE_LIMITED | 短时间内无效认证尝试过多 | 先修正 Key/认证配置，再按限制等待 |
上游 rate_limit_error 或其他限流提示 | 上游请求频率或容量限制 | 结合正文和 Retry-After 处理；持续出现时反馈 |
如果响应带 Retry-After，按它提示的等待时间处理。不是每个 429 都有这个头，也不是每个 429 都适合自动重试。不同协议的错误结构和代码可能不同，表中不是完整枚举。
超时和流式中断
先区分请求阶段：
| 发生阶段 | 观察什么 | 处理方式 |
|---|---|---|
| 连接建立前 | DNS、证书、连接或代理错误 | 检查系统时间、网络和工具实际代理；保留原错误，不关闭证书校验绕过问题 |
| 连接后一直无输出 | 首次响应等待时间、模型任务大小、客户端读取超时 | 先用短请求确认链路，再按任务合理设置超时 |
| 已有部分输出后断开 | 最后收到的事件、是否达到完成状态 | 保留部分内容并标成“未完成”，不要当完整结果继续处理 |
| 用户取消或页面关闭 | 客户端是否停止读取，后端是否取消任务 | 停止等待不等于上游已经停止，也不能据此认定不计费 |
客户端超时不等于服务端没有执行。 重发之前先按时间、Key 和模型检查使用记录，尤其是图片生成和长任务。
SSE 请求在开始时就可能返回 HTTP 200，后续仍可能发送错误或提前中断。Responses 的文字增量是 response.output_text.delta，完成应检查 response.completed；失败、不完整或缺少结束事件都需要单独处理。Chat Completions 与 Anthropic 的事件格式不同，不能用同一套事件名判断。完整示例见流式输出。
工具失败，但直接请求正常
用相同协议、Key、模型和短提示词比较，尽量保持网络环境相同。只跑通另一个协议或另一个模型，不能证明原配置没有问题。
| 你要验证的路径 | 使用的最小示例 |
|---|---|
| OpenAI Chat Completions | Chat Completions 请求 |
| Codex / Responses | Responses 请求 |
| Claude Code / Anthropic | Messages 请求 |
| Gemini | Gemini 原生请求 |
| 图片生成或编辑 | 生图指南 |
最小请求正常而工具仍失败时，再检查工具版本、实际生效的 Provider、环境变量、模型别名、代理和自动添加的参数。文字短请求成功，也不代表工具调用、长上下文或图片能力全部可用。
浏览器报 Network Error 或 CORS
Network Error 是客户端的汇总提示，不一定是 CORS。打开浏览器开发者工具的 Network 面板，检查请求是否发出、实际 URL、OPTIONS 预检和响应状态。
如果是自己开发的网页，浏览器应调用你自己的后端，由后端保管 BestAI Key 并访问 API；不要为了绕过报错把 Key 放到前端代码或公开构建变量里。链路示意见应用接入实践。
已有第三方客户端则按其官方的 Provider、代理或桌面模式配置排查，不把关闭浏览器安全检查当成正式解决方式。
请求追踪标识在哪里找
保留响应头中实际存在的 X-Client-Request-ID、X-Request-ID；某些错误或代理响应可能没有这些头，记录“未返回”即可。OpenAI Python SDK 的 HTTP 异常还可读取 request_id。
响应正文中的 response.id 和响应头中的请求标识不是同一个字段，反馈时分别标注。追踪标识用于定位请求，不是“同一个 ID 重发只扣一次”的承诺。不要把完整请求头、Cookie 或认证值整段贴出来。
反馈模板
先填写以下信息，再通过站点提供的支持入口提交：
text
发生时间与时区：
工具名称、版本、操作系统：
使用的协议与请求路径（不含密钥）：
模型 ID / 分组名称：
Key 标识（名称或编号，不填 Key 值）：
HTTP 状态 / 错误代码 / 脱敏错误正文：
响应头 X-Client-Request-ID / X-Request-ID（没有则填未返回）：
失败阶段（连接前 / 等待首个结果 / 输出中途 / 保存文件）：
是否收到部分结果：
是否自动或手动重试，重试次数：
对应使用记录是否找到（已检查时间和筛选）：
最小复现步骤、预期结果、实际结果：
已尝试的单项修改及结果：保留模型、参数名、状态和时间；删除真实 Key、Cookie、个人数据和业务正文。需要分享配置时，用 YOUR_API_KEY 替换密钥，检查图片链接是否带临时访问参数。通常不需要完整 Base64 图片、全部对话或原始 HAR 文件。