错误处理

① 保存错误码和报错信息 → ② 记录请求 ID 与时间 → ③ 按原因排查

错误码是排查线索，不是责任归属。客户端、本站、上游及中间代理都可能产生错误；最终以对应请求日志为准。

快速判断

400 / 401 / 403 / 404：先检查地址、密钥、模型和参数。

429：查看完整错误文字，区分余额、密钥限额与服务限流。

500 / 502 / 503：查看渠道状态，保留请求 ID。

504 / 522 / 524 / stream error：检查发生阶段，不要连续重复提交。

检查 JSON、必填字段、参数类型、模型支持的功能及上下文长度。先用一个最小请求验证，再逐步恢复图片、工具和长上下文。上下文超限与请求体字节过大不是同一件事。

检查是否使用本站 API 密钥，是否过期、删除或复制了空格。确认客户端确实发送 Authorization 认证头。不要把完整密钥发到群里或截图中。

可能涉及分组权限、IP 白名单、安全策略或上游访问限制，并不一定是账号被封。提供错误文字与请求 ID，由本站核对拒绝发生在哪一层。

检查 Base URL 是否重复拼接 /v1，以及所选模型是否在当前分组开放。不同客户端对 Base URL 的要求不同；接口不兼容时，不能只修改模型名来解决。

减少图片、附件、历史记录或工具描述，分批发送。限制可能来自客户端代理、本站或上游；提升模型上下文上限不一定能解决 HTTP 请求体大小限制。

先检查账户余额和 API 密钥的独立限额。若报错是速率或并发限制，降低并发，按 Retry-After 提示等待；没有提示时采用逐步延长间隔的有限重试。余额或权限问题不要反复重试。

HTTP 200 只说明响应已经开始，不保证整段回答成功。检查是否收到完成事件，留意客户端超时、代理断连和上游流内错误。可用稳定网络与最小请求对照，但不要直接认定都是客户网络问题。

保存请求 ID、时间和报错。可能发生在本站或上游，普通用户通常无法通过调整提示词解决。持续出现时提交反馈。

可能是上游返回错误、连接中断或响应格式异常。查看渠道状态，稍后有限重试；反复出现时提供模型和分组，便于定位具体路由。

可能是没有可用路由、临时容量不足、维护或上游不可用。不能仅凭 503 判断源头。本站会根据请求日志核对调度和上游状态。

504：网关等待后端响应超时。
522：Cloudflare 与源站建立连接或通信时发生连接超时。
524：Cloudflare 已连接源站，但等待响应或传输阶段超时。

出现 cf-ray 时请一并提供；有多层代理时，错误可能来自本站前面的 Cloudflare，也可能来自上游链路。长任务可减少上下文、拆分任务，并确认客户端支持流式响应。

确认 Base URL 不带重复 /v1；确认模型 ID 拼写；用一个最小请求（纯文本、单轮、无工具）对照；检查是否被旧环境变量覆盖。

提供：错误码、完整报错文字、请求 ID、发生时间（含时区）、模型与分组、客户端名称与版本、是否稳定复现。截图请遮挡密钥。