JetAPI / 报错排查手册

JetAPI 报错排查手册

按 HTTP 状态码整理的排查清单。每个错误给出实际返回内容、根因和验证命令, 而不是笼统的「检查配置」。 其中 「返回 200 但内容是 HTML」 这一类最隐蔽——看起来成功,实际路径写错了。

快速对照表

状态码返回内容关键词最常见根因跳转
401Invalid tokenKey 错误 / 未生效 / 鉴权头写错401
403用户额度不足余额 ≤ 0403
404Invalid URLBase URL 多了 /v1404
405Method Not AllowedBase URL 带了多余路径405
429rate_limit超过并发 / 速率429
500upstream_error上游异常500
503无可用渠道该模型无可用上游503
200HTML 而不是 JSONBase URL 少了 /v1200+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,不会扣成更深的负数。

处理

  1. 控制台首页看当前余额
  2. 充值后立即恢复,不需要重新建 Key 或重启服务
  3. 如果是某个 Key 的独立额度用完(而非账号余额),换一个 Key 或调整该 Key 的额度上限
余额可能是小幅负数。预扣 + 结算机制下,长上下文请求在结算时会补扣, 此时不看余额是否充足。负余额也算 ≤ 0,同样返回 403。

三、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 Codehttps://api.jetapi.icuhttps://api.jetapi.icu/v1
Codex CLI / OpenAI SDKhttps://api.jetapi.icu/v1https://api.jetapi.icu/v1/v1

四、405 Method Not Allowed

含义:路径存在但没有匹配的处理器。实测典型场景:

请求状态说明
POST /messages405Anthropic 端点漏了 /v1
POST /anthropic/v1/messages405Base URL 多带了 /anthropic

处理

Base URL 只填域名(Claude Code)或域名 + /v1(OpenAI 客户端),不要加任何其他路径段。

五、返回 200 但内容是 HTML(最隐蔽的一类)

这是比 404 更难排查的问题:HTTP 状态码是 200,看起来成功,但返回的是一段 HTML 页面。

实际观测

请求HTTPContent-Type实际内容
POST /v1/chat/completions401application/json真实端点(缺 Key)
POST /chat/completions200text/html站点的单页应用入口
GET /v1/models401application/json真实端点
GET /models200text/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 限流

含义:超过并发数或请求速率限制。

处理顺序

  1. 加指数退避重试:1s → 2s → 4s → 8s,不要固定间隔密集重试
  2. 降低并发:如果是批量任务,把并发数从 10 降到 2-3 试试
  3. 换线路:不同分组有不同并发上限,用另一个分组的 Key
  4. 如果持续超限,联系客服提升配额

指数退避示例

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 上游异常

含义:网关正常,但上游返回了错误。

处理:

八、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,用返回的真实名称,不要照抄官方文档。

九、通用排查流程

遇到报错时按这个顺序走,能快速定位是哪一层的问题:

  1. 直接用 curl 打端点,绕开所有 CLI 和 SDK
    能通 → 问题在 CLI 配置;不通 → 问题在 Key 或路径
  2. 检查 Content-Type
    text/html → 路径错了;application/json → 路径正确
  3. 检查鉴权头格式
    OpenAI 用 Authorization: Bearer,Anthropic 用 x-api-key
  4. 确认模型名
    用 GET /v1/models 拿真实名称
  5. 去后台看调用记录
    有记录 = 请求到了网关;无记录 = 请求没发出来

十、相关页面