---
title: "处理错误并准备生产接入"
description: "识别 XiuRouter 常见 HTTP 错误、判断能否重试，并完成 API Key、日志、超时和回滚检查。"
image: "https://docs.xiu.ai/og.png"
---

> XiuAI 文档索引
> 完整文档索引：https://docs.xiu.ai/llms.txt
> 阅读前先通过索引确认当前可用页面。

# 处理错误并准备生产接入

XiuRouter 的错误响应通常包含 `error.message`、`error.type` 和 `error.code`。同时记录响应头中的 `x-oneapi-request-id`，再根据状态码和控制台使用记录决定下一步。

## 错误响应

未提供有效 Key 时，响应形状类似：

```json
{
  "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` 对象和使用记录共同判断。

## 生产检查

1. 为每个应用创建独立 API Key，不共用人工测试 Key。
2. 选择明确的服务分组；使用自动分组时，核对尝试顺序和跨组重试是否会改变成本。
3. 限制可用模型、剩余额度和有效期。
4. 核对现有 Key 是否带有 IP 限制；控制台当前不提供该限制的编辑入口。
5. OpenAI Chat/Responses 使用 `https://router-api.xiu.ai/v1`；Anthropic Messages/Gemini 使用 `https://router-api.xiu.ai`。不要把控制台域名作为新客户端 Base URL。
6. 把 Key 放在服务端 Secret 或运行环境中，不进入浏览器包、仓库和日志。
7. 为连接、首字和总请求设置合理超时；长流式任务不要只依赖默认值。
8. 记录请求 ID、模型、协议、耗时和结果，不记录完整凭据和敏感输入。
9. 对 `429`、`5xx` 和未知结果设置告警，并定期核对“使用记录”。
10. 保留原 provider 配置和回滚步骤，切换后先跑只读小流量。

## 上线前验收

- 普通文本、流式、工具或结构化输出按实际用途分别通过。
- 测试 Key 的模型、分组、额度、有效期和 IP 范围符合预期。
- 失败请求能记录请求 ID，并能在控制台定位。
- 超时、`429`、上游 `5xx` 和余额不足有明确处理。
- 回滚后新请求恢复原 provider，旧 XiuRouter Key 可以撤销。

## 来源与核对日期

本文按 XiuRouter 当前鉴权、分发、限流、错误结构和控制台使用记录核对，日期为 2026-08-19。XiuRouter 未公开固定 SLA，也不保证第三方上游持续可用。

源文件：https://docs.xiu.ai/router/errors-and-production/index.mdx