我用 curl 排查了一次 OpenAI-compatible API 连接失败：401、403、404 分别怎么定位

用 curl 排查 OpenAI-compatible API 连接失败：401、403、404、usage 缺失怎么定位

最近接一些 OpenAI-compatible API 的时候，我发现一个问题挺常见：

配置看起来都填了，但客户端就是跑不起来。

比如 Cursor、Cline、Continue、Open WebUI 这类工具里，Base URL、API Key、Model ID 都填了，结果一请求就报错。

很多时候，问题不是模型本身，而是配置链路里某一段没通。

我现在一般按这个顺序排查：

vbnet 复制代码

Base URL → API Key → Model ID → 返回格式 → usage 字段 → 稳定性

1. 先确认 Base URL

很多 OpenAI-compatible API 会使用 /v1 路径：

arduino 复制代码

https://xxx.com/v1

但实际平台给你的地址可能有几种：

arduino 复制代码

https://xxx.com
https://xxx.com/v1
https://xxx.com/openai/v1

最容易出错的是重复 /v1：

bash 复制代码

https://xxx.com/v1/v1

所以第一步别急着进客户端，先用 curl 测一下：

bash 复制代码

curl https://xxx.com/v1/models \
  -H "Authorization: Bearer sk-xxxx"

如果返回的是 JSON，说明地址和 Key 至少有一部分是通的。

如果返回的是 HTML、登录页、404 页面，先别查模型，先查 URL。

2. 区分 401 和 403

401 一般是 Key 问题。

常见原因：

vbnet 复制代码

Key 复制错了
Key 过期了
Authorization header 格式不对
用了别的平台的 Key

403 一般更像权限问题。

比如：

vbnet 复制代码

Key 存在，但没有当前模型权限
用户组没有分配模型
余额不足
IP 或区域限制
某些辅助接口不允许访问

这里有个坑：有些网关的核心 chat 请求能通，但是 /models 或其他辅助接口会 403。

这种情况不能直接判断整个 API 不可用，要看核心请求是否能成功。

3. 再测 chat/completions

模型列表能返回，不代表某个模型一定能调。

可以发一个最小请求：

arduino 复制代码

curl https://xxx.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "ping"}
    ],
    "max_tokens": 8
  }'

如果这里返回 404 或 model not found，通常是 Model ID 不存在或当前 Key 没权限。

这类错误在 API 网关里很常见。Key 是有效的，但模型没分配。

4. 检查返回格式

正常的 OpenAI-compatible chat 返回，大概会有这些字段：

json 复制代码

{
  "id": "...",
  "object": "chat.completion",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "pong"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 2,
    "total_tokens": 12
  }
}

客户端一般会依赖这些字段：

css 复制代码

choices
message
content
usage

如果接口返回的是 HTML，或者 JSON 结构差异很大，客户端就可能解析失败。

5. usage 字段最好不要忽略

很多人只看能不能返回内容，不看 usage。

但 usage 很重要，因为它关系到后面对账。

比较基础的字段是：

复制代码

prompt_tokens
completion_tokens
total_tokens

如果这些都没有，接口也可能能用，但你很难核对这次请求到底消耗了多少。

有些接口还会返回缓存相关字段，比如：

复制代码

prompt_tokens_details.cached_tokens
cache_read_input_tokens
cache_creation_input_tokens

这个只能说明接口返回了缓存信号，不能直接证明底层缓存策略完全可靠。

6. 稳定性要多测几次

一次请求成功不代表稳定。

我一般至少看 5 次轻量请求：

复制代码

成功次数
平均延迟
最大延迟
中位数延迟
有没有长尾波动

大概可以这么看：

复制代码

2 秒以内：体验较好
2 - 3.5 秒：正常
3.5 - 6 秒：有轻微延迟
6 秒以上：需要关注

如果 5 次都成功，但有一次特别慢，我不会直接判定不可用。

更合理的判断是：能用，但存在长尾延迟，高成本任务前最好再测。

7. 一个简单排查清单

如果 OpenAI-compatible API 接不进去，可以按这个顺序查：

markdown 复制代码

1. Base URL 是否正确
2. 是否重复 /v1
3. API Key 是否有效
4. 当前 Key 是否有模型权限
5. Model ID 是否真实可调用
6. 返回是不是 JSON
7. choices/message/content 是否存在
8. usage 字段是否返回
9. 轻量请求是否稳定
10. 客户端配置是否和接口路径一致

8. 我后面做了一个小工具

手动 curl 可以解决问题，但每次都查这些字段比较麻烦。

所以我做了一个开源小工具，用来跑这些轻量检查：

复制代码

AI API Doctor

它主要检查 Base URL、API Key、Model ID、返回格式、usage 字段、缓存信号、模型身份信号和稳定性采样。

它不是用来证明模型真假，也不是长期监控，只是第一次接入前的 preflight check。

开源仓库：

bash 复制代码

https://github.com/JustinXai/ai-api-doctor-site

如果只是自己排查，也可以不依赖工具，按上面的 curl 步骤一步步查。

总结

OpenAI-compatible API 连接失败时，别一上来就怀疑模型。

更常见的问题是：

bash 复制代码

Base URL 写错
/v1 重复
Key 没权限
Model ID 不存在
返回格式不标准
usage 字段缺失
延迟不稳定

先用最小请求把链路拆开测，比在客户端里反复改配置更快。