JetAPI 报错排查手册
按 HTTP 状态码整理的排查清单。每个错误给出实际返回内容、根因和验证命令, 而不是笼统的「检查配置」。 其中 「返回 200 但内容是 HTML」 这一类最隐蔽——看起来成功,实际路径写错了。
快速对照表
| 状态码 | 返回内容关键词 | 最常见根因 | 跳转 |
|---|---|---|---|
| 401 | Invalid token | Key 错误 / 未生效 / 鉴权头写错 | 401 |
| 403 | 用户额度不足 | 余额 ≤ 0 | 403 |
| 404 | Invalid URL | Base URL 多了 /v1 | 404 |
| 405 | Method Not Allowed | Base URL 带了多余路径 | 405 |
| 429 | rate_limit | 超过并发 / 速率 | 429 |
| 500 | upstream_error | 上游异常 | 500 |
| 503 | 无可用渠道 | 该模型无可用上游 | 503 |
| 200 | HTML 而不是 JSON | Base URL 少了 /v1 | 200+HTML |
一、401 Invalid token
含义:请求到达了端点,但鉴权失败。
逐个排查
| 检查项 | 做法 |
|---|---|
| Key 是否完整 | 从控制台重新复制。注意首尾空格、换行、被截断(有些终端复制会丢字符) |
| Key 是否被停用 | 控制台「API Key」页看状态是否为启用 |
| 鉴权头是否正确 | OpenAI 协议用 Authorization: Bearer sk-xxx;Anthropic 协议用 x-api-key: sk-xxx + anthropic-version: 2023-06-01 |
| 是否用了别的平台的 Key | 确认以 sk- 开头,且是本端点签发的 |
| 环境变量是否真的生效 | 直接 curl 端点(绕开 CLI),排除 CLI 缓存问题 |
验证命令
curl https://api.jetapi.icu/v1/models \
-H "Authorization: Bearer sk-你的密钥"
返回模型列表 = Key 有效,问题在 CLI 配置;返回 401 = Key 本身有问题。
CLI 场景的额外检查
改了 Key 但 CLI 仍报 401,通常是进程缓存了旧的环境变量。完全退出所有相关进程:
# Windows
Get-Process | Where-Object { $_.ProcessName -match 'claude|node' } | Stop-Process
# macOS / Linux
pkill -f claude
二、403 用户额度不足
含义:鉴权通过,但账户余额 ≤ 0。
JetAPI 的预扣检查是:
UPDATE users SET quota = quota - ? WHERE id = ? AND quota >= ?
余额不足时影响行数为 0,直接返回 403,不会扣成更深的负数。
处理
- 控制台首页看当前余额
- 充值后立即恢复,不需要重新建 Key 或重启服务
- 如果是某个 Key 的独立额度用完(而非账号余额),换一个 Key 或调整该 Key 的额度上限
三、404 Invalid URL
含义:路径不存在。实际返回示例:
POST /v1/v1/messages
{
"error": {
"message": "Invalid URL (POST /v1/v1/messages)",
"type": "invalid_request_error"
}
}
根因
Base URL 多写了 /v1,客户端又自己拼了一次,变成双重前缀。
| 客户端 | 正确 Base URL | 触发 404 的写法 |
|---|---|---|
| Claude Code | https://api.jetapi.icu | https://api.jetapi.icu/v1 |
| Codex CLI / OpenAI SDK | https://api.jetapi.icu/v1 | https://api.jetapi.icu/v1/v1 |
四、405 Method Not Allowed
含义:路径存在但没有匹配的处理器。实测典型场景:
| 请求 | 状态 | 说明 |
|---|---|---|
POST /messages | 405 | Anthropic 端点漏了 /v1 |
POST /anthropic/v1/messages | 405 | Base URL 多带了 /anthropic |
处理
Base URL 只填域名(Claude Code)或域名 + /v1(OpenAI 客户端),不要加任何其他路径段。
五、返回 200 但内容是 HTML(最隐蔽的一类)
这是比 404 更难排查的问题:HTTP 状态码是 200,看起来成功,但返回的是一段 HTML 页面。
实际观测
| 请求 | HTTP | Content-Type | 实际内容 |
|---|---|---|---|
POST /v1/chat/completions | 401 | application/json | 真实端点(缺 Key) |
POST /chat/completions | 200 | text/html | 站点的单页应用入口 |
GET /v1/models | 401 | application/json | 真实端点 |
GET /models | 200 | text/html | 同样是 HTML |
客户端会怎么表现
SyntaxError: Unexpected token '<', "<!doctype "... is not valid JSON
或者:
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
看起来像 SDK 问题,实际是 Base URL 少了一段路径。
怎么确认
# 打印原始响应,不要直接 JSON.parse
curl -i https://api.jetapi.icu/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{}'
看 Content-Type:
| Content-Type | 结论 |
|---|---|
application/json | 路径正确,问题在别处 |
text/html | 路径错了,补 /v1 |
修复
OpenAI 协议的客户端,Base URL 必须是 https://api.jetapi.icu/v1,不能只写域名。
六、429 限流
含义:超过并发数或请求速率限制。
处理顺序
- 加指数退避重试:1s → 2s → 4s → 8s,不要固定间隔密集重试
- 降低并发:如果是批量任务,把并发数从 10 降到 2-3 试试
- 换线路:不同分组有不同并发上限,用另一个分组的 Key
- 如果持续超限,联系客服提升配额
指数退避示例
import time, random
def with_retry(fn, max_tries=5):
for i in range(max_tries):
try:
return fn()
except RateLimitError:
if i == max_tries - 1:
raise
# 1s, 2s, 4s, 8s(带抖动避免同时重试)
time.sleep((2 ** i) + random.random())
七、500 上游异常
含义:网关正常,但上游返回了错误。
处理:
- 重试一次(上游偶发错误很常见)
- 持续 500 时换一条线路
- 看服务状态页确认该线路是否异常
八、503 无可用渠道
含义:该模型当前没有可用上游。实际返回通常包含 无可用渠道 或 No available channel for model xxx。
三种可能
| 原因 | 验证方法 |
|---|---|
| 模型名拼写错误 | GET /v1/models 比对真实名称 |
| 该分组不支持这个模型 | 换一个支持该模型的分组的 Key |
| 上游临时故障 | 换模型或稍后重试 |
一个实际案例
图像模型如果填官方名 gpt-image-1 会报 No available channel for model gpt-image-1,
因为实际可用的模型名是 gpt-image-2.6、gpt-image-2.5 系列。
接任何新模型前,先跑一次 GET /v1/models,用返回的真实名称,不要照抄官方文档。
九、通用排查流程
遇到报错时按这个顺序走,能快速定位是哪一层的问题:
-
直接用 curl 打端点,绕开所有 CLI 和 SDK
能通 → 问题在 CLI 配置;不通 → 问题在 Key 或路径 -
检查 Content-Type
text/html→ 路径错了;application/json→ 路径正确 -
检查鉴权头格式
OpenAI 用Authorization: Bearer,Anthropic 用x-api-key -
确认模型名
用GET /v1/models拿真实名称 -
去后台看调用记录
有记录 = 请求到了网关;无记录 = 请求没发出来