报错排查

1. 按状态码排查

先用下表定位，再看对应小节的处理方式。

状态码	典型原因	能否重试
`400`	请求结构、必填字段或模型 ID 有问题	否，先修请求
`401`	鉴权失败	否，先修请求
`402`	余额不足或达到消费上限	否，先充值
`424`	上游基础设施出错	可以，指数退避加抖动
`429`	限流或重复请求保护	可以，按响应头退避
`5xx`	可恢复的网关或上游错误	可以，指数退避加抖动

1.1 收到 400 怎么办？

通常是 invalid_request_error 或 model_not_found。检查 JSON 结构与必填字段，并确认模型 ID 和端点来自当前 Key 的 GET /v1/models，同时检查渠道与模型权限。

invalid_callback_url 表示 POST /v1/router/task/create 的 callback_url 不是公网 HTTPS 地址。只有本地部署才接受 HTTP。超过 2048 个字符、带用户名或密码，或指向回环、内网、链路本地、元数据地址、localhost 时也会返回这个错误。任务不会创建。

不要重试。

鉴权失败。可能是本平台 API Key 无效，也可能是上游原样返回了 401。先检查 API Key 是否存在、是否仍启用、格式是否正确（Authorization: Bearer sk-...、x-api-key: sk-...；Gemini 原生接口和 GET /v1/models 还可以用 x-goog-api-key 或 ?key=）。error.code 为 missing_key 表示没带 Key；conflicting_keys 只出现在这两个入口，表示多个来源的 Key 不一致，或某个来源是空值而另一个来源有 Key；invalid_key 表示 Key 不存在或已停用。

不要重试，先修请求。

1.3 收到 402 怎么办？

余额不足，或当前 API Key 达到消费上限。请充值，或改用未达到上限的 Key。

不要重试。

1.4 收到 424、error.code 是 provider_error 怎么办？

上游基础设施出错，网关已把供应商细节收敛掉，只给你一个中性错误和请求 ID。

记录请求 ID（错误消息里带，或读 X-AIToken-Request-Id / X-OneAPI-Request-Id 响应头），然后在业务层用指数退避 + 抖动做次数受控的重试。

1.5 收到 429 怎么办？

先检查 error.code 和响应头：

account_rpm_limit：按 RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset 退避。
account_concurrency_limit：等待 Retry-After 指定的秒数。
没有账户限流 code 和响应头：可能是 10 秒内第 4 次发送完全相同的请求，也可能是上游返回了 429。

详见计费与额度。

1.6 收到 5xx，或图片接口返回 504 怎么办？

upstream_error、api_error、internal_error、timeout_error 属于可恢复错误，可以重试。

图片接口返回 504 时不要重新提交——任务仍在运行，继续轮询 task_id 即可。

2. 重试与流式失败

2.1 哪些错误不该重试？

400、401、402 不要重试，先修请求或充值。

可以受控重试的是 424、429 和可恢复的 5xx，一律用指数退避加抖动，并限制次数。

2.2 流式响应中途断了，怎么判断这次失败了？

两种情况都按失败处理：

收到了协议对应的 provider_error 终止事件。
流结束了，却没有收到该协议的正常完成事件。

原因是上游流在 HTTP 200 提交之后才读取失败，状态码已经无法改成 424；网关会在连接仍可写时追加且只追加一次带请求 ID 的 provider_error 事件，然后关闭流。客户端或连接已经断开时这个事件送不到，只剩服务端日志。

联系支持时请提供事件正文里的请求 ID，或 X-AIToken-Request-Id / X-OneAPI-Request-Id 响应头。

3. 错误响应结构

错误结构按接口族不同：

接口族	结构
LLM 与 Responses	`{ "error": { "message", "type", ... } }`
媒体异步任务	`{ "code": 402, "message": "...", "task_id": "" }`
OpenAI 兼容图片端点	`{ "error": { "message", "type", "code" } }`

LLM 常见 type 有 invalid_request_error、model_not_found、authentication_error、insufficient_quota、rate_limit_error、api_error、internal_error；Anthropic 与 Gemini 返回各自的原生结构。媒体任务不使用 LLM 账户限流，也不再占用已退役的按 Key / 按 IP 共享额度。

完整说明见错误码。