Skip to main content
XRouter 的 relay 接口通常返回 OpenAI 兼容错误结构： 
{
  "error": {
    "message": "token invalid",
    "type": "new_api_error",
    "param": "",
    "code": "invalid_request"
  }
}
某些上游错误会保留上游的错误类型或错误码。排查时请同时查看 HTTP 状态码、error.code、error.message 和控制台用量日志。

​
常见 HTTP 状态码

状态码常见原因排查方向
400请求体格式错误、缺少必填字段、模型参数不兼容对照对应 API 页面检查 JSON、模型名和参数
401API Key 缺失或无效确认 Key 完整，认证头格式正确
403用户、Key、分组、额度或 IP 限制不允许访问检查 Key 状态、模型限制、IP 限制和账户状态
429请求触发频率限制或上游限流降低并发，稍后重试，检查工具是否在循环重试
500XRouter 或上游返回异常查看控制台日志中的请求详情和错误信息
502 / 503上游不可用、无可用渠道或服务临时异常更换模型或稍后重试

​
常见 error.code

code含义常见处理
invalid_request请求格式或参数不合法检查 JSON、必填字段、模型名和接口格式
access_denied访问被拒绝检查 Key 的 IP 限制、分组权限或账户状态
model_not_found模型不存在或当前 Key 不可用从控制台复制模型 ID，并用 /v1/models 验证
insufficient_user_quota账户或 Key 可用额度不足到控制台检查账户和 Key 状态
pre_consume_token_quota_failed请求预扣费失败检查 Key 额度、账户状态和请求预估消耗
channel:no_available_key当前模型没有可用上游渠道更换模型或稍后重试
channel:model_mapped_error模型映射失败确认模型 ID 是否来自控制台
bad_response_status_code上游返回非成功状态码查看日志中的上游错误信息
bad_response_body上游响应体无法解析记录请求 ID，并查看控制台日志详情
empty_response上游返回空内容重试或更换模型
prompt_blocked请求内容被上游安全策略拦截修改输入内容或更换符合要求的模型

​
请求失败时的最小排查流程

1

验证 Key

使用同一把 Key 请求 /v1/models，确认认证和服务地址可用。
2

确认接口格式

OpenAI SDK 使用 /v1 和 Bearer token；Claude Code 使用服务根地址；Gemini 客户端使用 /v1beta。
3

复制模型 ID

从控制台复制模型 ID，避免手动输入造成大小写或后缀错误。
4

查看用量日志

在控制台按时间、模型或 Key 查找失败请求，确认完整错误信息。