错误与连接排查
HTTP、SSE、WebSocket 和 TLS 故障
HTTP 错误
| 状态 | 处理 |
|---|---|
| 400 / 422 | 检查字段、枚举、协议、内容格式和型号约束；修改后再提交，不重复发送原错误请求 |
| 401 | 核对 Key、认证头、失效状态和客户端覆盖配置 |
| 403 | 查看错误正文，确认权限、策略、额度或预扣原因 |
| 404 | 核对接口路径和任务 ID，路径错误也会返回此状态 |
| 413 | 请求体过大；压缩、拆分并核对 Base64 膨胀后的总大小 |
| 429 | 区分速率、并发和额度；遵守 Retry-After，限制重试次数 |
| 500 / 502 / 503 / 504 | 保留 request ID 与正文；查询可退避重试，生成 POST 避免重复提交 |
排查时保留 HTTP 状态、Content-Type、request ID 和脱敏后的错误正文。正文可能是 JSON、网关 HTML 或纯文本；.json() 解析失败时仍应保留原始状态和正文。
协议内错误
HTTP 200 表示接口返回了响应，业务结果还需读取协议字段：Responses 的 failed / incomplete、Chat 的 finish_reason、Claude 的 stop_reason、Gemini 的 finishReason、MJ 的 status，以及 Realtime 的 response.done。SSE / WebSocket 的 error 事件按错误处理。
诊断信息包括 error.message、error.type、error.code、嵌套错误和平台 message 字段。写日志前删除其中的密钥、签名 URL、文件正文和个人信息。
网络与证书
DNS 解析、TCP 连接、TLS 握手、HTTP 响应和模型生成是不同阶段。浏览器、终端、CC Switch、VS Code、WSL 可能各用不同代理与证书库。
Windows 上的 Python requests 可能读取系统代理。遇到 ProxyError 时检查代理地址、证书路径和 NO_PROXY。若网络策略允许，可为目标域名配置直连，TLS 验证保持开启。
有效期内的证书也可能出现证书吊销、证书链缺失、域名不匹配、本机时间错误或吊销服务不可达。请按具体错误排查，保留 HTTPS 校验，不向未确认的 IP 或 HTTP 地址发送 Key。
Gemini 返回 thought signature 错误时，检查 model parts、签名和消息顺序是否完整，并保留 request ID。签名应原样回传；完整历史仍失败时，请联系平台排查会话兼容性。也可以由应用另行发起新的参考图编辑，上传上一轮成图，但这会创建新请求，并非恢复原对话。
重试原则
无副作用的 GET 可有限次数退避重试，明确的参数错误需修改后再提交。生成类 POST 超时后可能已经受理，直接重发可能重复生成。MJ 已收到 id 时继续查询原任务；Realtime 重连前先处理旧工具和音频状态。
向平台反馈时，请附发生时间、模型 ID、路径、脱敏 request ID、HTTP 状态和最小复现请求，并移除完整 Authorization、API Key、Cookie 及私有文件。