错误码

XRouter 的 relay 接口通常返回 OpenAI 兼容错误结构：

{
  "error": {
    "message": "token invalid",
    "type": "new_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

某些上游错误会保留上游的错误类型或错误码。排查时请同时查看 HTTP 状态码、error.code、error.message 和控制台用量日志。

常见 HTTP 状态码

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`	请求内容被上游安全策略拦截	修改输入内容或更换符合要求的模型

验证 Key

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

确认接口格式

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

复制模型 ID

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

查看用量日志

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