OpenAI API 报错排查指南：401、404、模型不存在、流式输出失败怎么处理

先记一个排查顺序

大多数问题都可以按这个顺序查：base_url → path → api_key → model → 请求体 → 输出格式 → 超时/流式。不要一上来就怀疑模型，很多时候只是地址或字段写错了。

一、401 Unauthorized

这是最常见的错误之一，通常说明令牌、鉴权头或权限有问题。

确认是否带了 Authorization: Bearer sk-xxx
确认 token 是否复制完整
确认是否把测试环境 token 用到了生产环境
确认服务端是否错误地把 header 吃掉了

二、404 Not Found

404 大多数不是服务挂了，而是路径拼错了。

正确示例：
https://api.bangban.xin/v1/chat/completions

检查有没有漏掉 /v1
检查是否把 /chat/completions 写成别的路径
检查 SDK 的 base_url 是否自动拼了路径，导致重复

三、模型不存在 / model not found

这类问题通常是模型名不匹配，不一定是平台完全不可用。

确认你填的模型名是否在当前网关里可用
不要想当然把官方模型名原样照搬
如果后台做了模型映射，确认映射规则
先用一个已知可用模型做基线测试

四、流式输出失败 / stream 卡住

如果普通请求能返回，但 stream 有问题，常见原因在中间层。

检查代理层是否支持 SSE / chunked 响应
检查前端是否按流式读取，而不是等整包
检查服务器超时设置和反向代理缓冲
先关闭 stream 做对照测试

五、JSON 解析失败

这通常不是 API 故障，而是你期待结构化输出，但模型实际回了一段自然语言。

你是结构化输出助手。
只输出 JSON，不要附加解释。
格式如下：
{"category":"...","summary":"..."}

如果业务流程依赖字段解析，提示词一定要收紧。

六、上下文过长 / token 超限

常见于知识库、长文档、聊天历史太长的场景。

缩短历史消息，只保留必要上下文
文档先切块，不要整本塞进去
把系统提示词写短一点
需要时改用更适合长上下文的模型

七、最小可用请求，先拿它做基线

curl https://api.bangban.xin/v1/chat/completions \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

先让这个最小请求通，再去加流式、JSON 输出、上下文、工具调用。

八、上线排查建议

把 base_url、model、token 分开配置，便于定位
前后端都打错误日志，但不要泄露完整 token
为不同业务场景设置不同 token
先验证普通请求，再验证流式请求
每次只改一个变量，不要同时改路径、模型和提示词

九、为什么这篇适合做 SEO 长尾页

搜索错误码的人，大多已经在接入阶段了，意图非常强。相比泛泛讲“什么是 AI Gateway”，这种排障文章更容易吃到精准流量，也更容易把用户带到文档页和教程页。