# 常见问题
> 接入时最常遇到的问题与解决办法
> 按接入、报错、使用、账户四块分组
> 报错细节见[错误码与限流](errors.html)，安全与网络见[网络与安全](security.html)
## 接入
**Base URL 到底带不带 `/v1`？**
这是最高频的问题。判断依据是看工具文档里写的是「base URL」还是「完整端点」：
| 说法 | 填写方式 |
|---|---|
| base URL / API 域名 | `https://api.oairoute.com`（不带 `/v1`） |
| 完整端点 | `https://api.oairoute.com/v1/chat/completions` |
| SDK 的 base_url 参数 | `https://api.oairoute.com/v1` |
同一个值填错位置，表现就是 404。各客户端的具体填法见[接入概览](../integrations/index.html)。
**模型名填什么？** 填 `GET /v1/models` 返回的 `id`。不同分组看到的清单不同，详见[模型列表接口](../api/models.html)。
**Key 是哪种格式？** `sk-` 开头的一串字符，放在 `Authorization: Bearer` 头里。
**可以把 Key 放在 URL 里吗？** 不可以，网关会拒绝查询参数形式的密钥，请改用请求头。
**两个域名怎么分工？**
| 域名 | 覆盖 |
|---|---|
| `api.oairoute.com` | 文本、语音、任务查询、账户用量，以及除 Seedance、Seedream 之外的图像视频 |
| `ark.oairoute.com` | Seedance 系列与 Seedream 系列 |
注意两个站点的 Key 与额度是分开的，ark 站需要单独获取 Key。
## 排查顺序
遇到问题按这三步走，大部分情况能自己定位。
**第一步：先确认 Key 有效。**
```bash
curl https://api.oairoute.com/v1/models \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY"
```
返回模型列表说明认证没问题，问题在后续参数；返回 401 就是 Key 本身的问题。
**第二步：确认模型存在。**
上一步返回的列表里找一下你要用的模型 ID，没有就是该账号未开通。
**第三步：用最小请求试。**
```bash
curl https://api.oairoute.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"hi"}]}'
```
最小请求能通，说明接入没问题，问题在你自己的请求体。
## 报错
**401** Key 复制不完整、已删除或已停用。到控制台「令牌」页核对。
**402** 余额不足。到控制台[钱包](https://api.oairoute.com/wallet)页面充值。
**403** 无访问权限，或 Key 所在分组不允许调用该模型。换用分组内的可用模型。
**404** 路径或资源不存在。先确认地址有没有多写或少写 `/v1`，再确认模型名是否正确。
**429** 触发限流。按响应头 `Retry-After` 的指示等待，或降低并发。
**500 / 502 / 503** 服务端或上游异常，网关已做过重试。稍等几秒再试一次。
完整的错误码、错误结构与含义见[错误码与限流](errors.html)。
## 使用
**返回内容为空？**
- **流式场景**：检查是否解析了 `choices[0].delta.content`。首条消息里的 `delta` 只含 `role`，`content` 是 `null`，直接取会得到空值
- **非流式场景**：看 `finish_reason`。如果是 `length`，说明被 `max_tokens` 截断了，把上限调大
- **内容审核拦截**：部分模型会返回空的 `content`，同时 `finish_reason` 为 `content_filter`
**流式输出中途断了？** 先检查客户端是否处理了流内的 `error` 事件。网络中间设备可能提前关闭长连接，建议在客户端配置更长的读超时。
**请求特别慢？** 按影响程度排序：
1. 上下文太长。每轮都重发全部历史，输入越长首 token 越慢
2. 模型太大。旗舰模型的推理本身就慢
3. 网络链路。跨境访问有额外延迟，可换直连线路试试
**中文乱码？** Windows 终端默认不是 UTF-8，先执行 `chcp 65001` 再跑命令。写入文件时也要显式指定编码，Python 用 `encoding="utf-8"`。
**并发上不去？** 429 是限流信号，不是服务坏了：
- 用信号量把并发压在 5 到 10
- 遇到 429 按指数退避重试
- 需要更高并发时，拆成多个 Key 分担
**为什么实际扣费和官方价格不一样？** 实际扣费 = 用量 × 单价 × 分组倍率。你的分组系数在控制台能看到，算账方法见[计费说明](../api/billing.html)。
**同一把 Key 能同时调 Claude 和 GPT 吗？** 取决于 Key 所在分组。分组决定了你这把 Key 能调哪些模型，清单见 `GET /v1/models`。
**用量记录多久出现？** 调用结束后写入，流式请求在流结束时写入。可在控制台[用量](https://api.oairoute.com/usage-logs)页面查看。
## 账户
**忘记密码？** 登录页点「忘记密码」，通过邮箱重置。
**额度用完了会怎样？** 产生费用的接口会被拒绝，查询类接口仍可调用，充值后立即恢复。
**没找到答案？** 写邮件到 [support@oairoute.com](mailto:support@oairoute.com)，附上请求时间、接口路径、HTTP 状态码与完整错误体，以及你的 Key 名称（不要贴完整 Key）。