XiuRouter 的错误响应通常包含 error.message、error.type 和 error.code。同时记录响应头中的 x-oneapi-request-id，再根据状态码和控制台使用记录决定下一步。
错误响应
未提供有效 Key 时，响应形状类似：
{
"error": {
"code": "",
"message": "Invalid token (request id: ...)",
"type": "new_api_error"
}
}不要从错误文本中提取或记录 API Key、上游凭据、完整提示词或敏感输入。
常见状态码
| 状态码 | 常见原因 | 处理 |
|---|---|---|
400 |
JSON、参数或协议不被接受 | 缩小为最小请求，按错误字段修正，不自动重试 |
401 |
Key 缺失、无效或已撤销 | 检查进程环境和 Key 状态，必要时轮换 |
403 |
账号、IP、分组、模型或额度限制 | 检查 Key 范围、账号余额和服务分组 |
404 |
路径不存在 | 检查 Base URL 和接口；/v1/messages/count_tokens 当前没有专用路由，但 Claude Code 可回退到 Messages |
429 |
请求频率超过当前限制 | 降低并发，等待后再有限重试 |
5xx |
网关或上游暂时失败 | 记录请求 ID，先查使用记录，再决定是否重试 |
模型没有可用渠道时，网关也可能返回 503 和 model_not_found。这不一定表示模型 ID 拼错；还要核对该 Key 的服务分组、模型范围和当前目录。
重试规则
400、401、403、404：修正请求或配置后再发，不做自动重试。429、部分5xx、网络断开：使用有上限的退避重试，并限制总耗时。- 超时或连接中断：结果可能已发生。先到“使用记录”按请求 ID、时间和模型核对，不要直接重复提交。
- 工具调用、外部写入或其他不可重复任务：由应用自己提供幂等控制；XiuRouter 不替你保证业务操作只执行一次。
不要复制参考服务的固定重试次数或错误语义。XiuRouter 会透传或转换不同上游的错误，应用应以 HTTP 状态、error 对象和使用记录共同判断。
生产检查
- 为每个应用创建独立 API Key，不共用人工测试 Key。
- 选择明确的服务分组；使用自动分组时，核对尝试顺序和跨组重试是否会改变成本。
- 限制可用模型、剩余额度和有效期。
- 核对现有 Key 是否带有 IP 限制；控制台当前不提供该限制的编辑入口。
- OpenAI Chat/Responses 使用
https://router-api.xiu.ai/v1；Anthropic Messages/Gemini 使用https://router-api.xiu.ai。不要把控制台域名作为新客户端 Base URL。 - 把 Key 放在服务端 Secret 或运行环境中，不进入浏览器包、仓库和日志。
- 为连接、首字和总请求设置合理超时；长流式任务不要只依赖默认值。
- 记录请求 ID、模型、协议、耗时和结果，不记录完整凭据和敏感输入。
- 对
429、5xx和未知结果设置告警，并定期核对“使用记录”。 - 保留原 provider 配置和回滚步骤，切换后先跑只读小流量。
上线前验收
- 普通文本、流式、工具或结构化输出按实际用途分别通过。
- 测试 Key 的模型、分组、额度、有效期和 IP 范围符合预期。
- 失败请求能记录请求 ID，并能在控制台定位。
- 超时、
429、上游5xx和余额不足有明确处理。 - 回滚后新请求恢复原 provider，旧 XiuRouter Key 可以撤销。
来源与核对日期
本文按 XiuRouter 当前鉴权、分发、限流、错误结构和控制台使用记录核对，日期为 2026-08-19。XiuRouter 未公开固定 SLA，也不保证第三方上游持续可用。