> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiohub.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

> 常见错误排查指南与调试方法。

## 先检查连接

排障先确认客户端能连接到 AIOHub，并且 API 令牌、分组和协议配置匹配当前模型。

* **连接失败**：检查客户端 Base URL、本地代理、防火墙和 API 令牌环境变量。
* **服务返回错误**：按状态码、模型名、分组、请求 ID 和返回错误继续排查。
* **客户端显示失败**：检查客户端是否无法解析返回格式，或是否把同一操作重试后显示了后一次错误。

## 常见问题排查

### 客户端 Base URL 配错

不要把完整端点填进客户端的 Base URL 字段。报错里出现 `/v1/v1`、`/chat/completions/chat/completions` 或重复的 `/v1beta` 时，通常是客户端配置里多填了一段路径。按 [选择客户端](/cn/clients) 核对对应协议的 Base URL。

### 400 错误

通常是请求格式、参数或协议不匹配。先确认你使用的端点和请求体属于同一种协议，例如 OpenAI Chat Completions、OpenAI Responses、Claude Messages 或 Gemini API。客户端会话状态导致的 400，请查看对应客户端页面。

### 401 或 403 错误

401 通常是 API 令牌无效、过期或请求头格式错误。403 通常是当前分组无权访问请求的模型或端点。检查 API 令牌是否启用、余额是否足够、分组是否包含目标模型，并按客户端页面核对协议与 Base URL。

### API Connect Error

* 检查本地网络连接
* 检查代理设置是否正确
* 确认客户端 Base URL 没有重复路径
* 尝试请求模型列表验证 API 令牌和网络：

```bash theme={"system"}
curl https://api.aiohub.org/v1/models \
  -H "Authorization: Bearer sk-你的API令牌"
```

### 请求超时

* 检查网络延迟
* 部分模型响应较慢属正常现象
* 减小输入规模或切换模型后重试

### 模型不可用

模型可用性由当前服务状态、API 令牌的分组和模型所在端点共同决定。先查看控制台模型定价页，或请求 `/v1/models` / `/v1beta/models` 确认当前 API 令牌可见的模型列表。

## 获取帮助

以上方法无法解决时，整理请求时间、请求 ID、模型名、API 令牌名、客户端名称、Base URL 和错误信息，再查看 [常见问题](/cn/support/faq) 和控制台公告。