故障排查

先判断错误发生在客户端配置、QuotaAPI 鉴权与调度、目标模型，还是支付服务商。不要在原因未知时无限重试，否则会放大限流、重复任务或重复支付。

最小诊断信息

记录以下内容：

时间与时区。
请求方法和路径。
模型、分组名和 API Key 名称。
HTTP 状态码、响应体错误和 request_id。
是否流式、是否图片/视频、客户端名称和版本。
可复现的最小请求。

不得记录或发送完整 Authorization、API Key、Cookie、支付密钥或对象存储凭证。

状态码速查

状态码	常见含义	首要检查
`400`	请求体、参数、模型或协议不合法	对照端点文档和最小 curl
`401`	API Key 缺失、失效或格式错误	Bearer 头、Key 状态、客户端变量
`402`	USD 余额或订阅额度不足	余额、周期额度和最近扣费
`403`	分组、模型、图片能力或 IP 规则无权限	Key 绑定分组、功能开关、IP 规则
`404`	端点不受该平台支持，或资源不属于当前 Key	兼容矩阵、资源 ID
`429`	用户、Key、账号或目标平台限流	`Retry-After`、并发、周期额度
`500` / `502`	服务端或目标平台异常	`request_id`、稍后有限重试
`503`	没有可调度账号或依赖暂不可用	分组账号池、模型映射、冷却状态

用 curl 隔离客户端问题

bash

curl -i https://quotarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [{"role":"user","content":"Reply with OK"}],
    "max_tokens": 16
  }'

curl 成功而 SDK 失败，重点检查 Base URL、环境变量、代理、超时和客户端使用的协议。curl 也失败则保留完整状态码和脱敏响应体。

客户端配置

Claude Code 使用 Anthropic Messages Base URL。
Codex CLI 需要 config.toml、auth.json 和 wire_api = "responses"。
Gemini CLI 使用 GOOGLE_GEMINI_BASE_URL、GEMINI_API_KEY 和 GEMINI_MODEL。
OpenAI SDK 通常把 Base URL 设为 https://quotarouter.ai/v1。

不要把 /v1 重复拼接成 /v1/v1，也不要把控制台登录 Token 当成 API Key。

账号测试成功但 API 返回 503

后台账号测试按指定账号直连，只证明凭证和目标平台可用。用户 API 还需要经过：Key 绑定分组、平台匹配、模型映射、账号可调度状态、并发、额度和冷却过滤。检查：

日志中的 group_id、provider、model 和 account_select_failed。
账号是否在该分组、平台是否一致。
请求模型是否能映射到账号支持的模型。
账号是否被 429、402、认证失败或并发临时冷却。

429 但账号看起来可用

429 可能只限制某个模型、地区、项目、时间窗口或并发，不代表账号永久失效。客户端应遵循 Retry-After 并限制重试。多个账号时，系统会按策略切换；全部候选都处于冷却或不匹配时，用户侧可能最终看到 503。

流式回复为空或刷新后才出现

先等待聊天页面的 reconciling 状态。服务端可能已经保存回复，但 SSE 连接没有把最后内容交给浏览器。记录会话 ID、request_id 和浏览器网络错误。API 客户端则应区分正常 [DONE]、错误事件和连接提前结束。

图片与视频

图片聊天最长等待 120 秒；进行中不要重复发送。
API 长耗时图片优先使用异步任务并轮询原 task_id。
404 常表示分组平台不支持媒体接口或功能未开启。
视频只走 Grok 目标，查询必须使用原用户和原 API Key。
上传失败先检查格式、大小和对象存储配置。

支付与充值

amount is too small：低于服务商或币种的最小金额。
支付方式不可用：实例未启用、币种不支持、金额超限、地区/设备不满足或当日容量已满。
已扣款未到账：不要重复支付，刷新订单状态并保存订单号。
HKD 实付与 USD 到账不同是正常换算；查看订单 fx_rate 和支付币种。
加密货币必须核对网络、地址和精确金额。

提交工单

完成以上步骤仍无法定位时，通过工单与支持提交时间、端点、模型、分组、状态码、request_id 和最小复现。支付问题附订单号，批量图片附批次 ID；不要附秘密凭证。

故障排查 ​

最小诊断信息 ​

状态码速查 ​

用 curl 隔离客户端问题 ​

客户端配置 ​

账号测试成功但 API 返回 503 ​

429 但账号看起来可用 ​

流式回复为空或刷新后才出现 ​

图片与视频 ​

支付与充值 ​

提交工单 ​