API 中转站返回 401、403、404 分别代表什么？一张表定位鉴权与模型配置错误
用状态码快速定位 API 中转站的鉴权、权限、Base URL 和模型 ID 问题，附 curl 验证命令与排查清单。
API 中转站返回 401、403、404 分别代表什么？一张表定位鉴权与模型配置错误
调用 API 中转站时，401、403 和 404 都可能被误认为“服务商挂了”，但它们通常对应不同的配置问题。先看 HTTP 状态码，再核对请求地址、密钥、模型 ID 和账户权限，排查会快很多。
三种状态码先分清
| 状态码 | 常见含义 | 优先检查 |
|---|---|---|
| 401 | 未通过身份验证 | Authorization、Key 是否为空或已失效 |
| 403 | 身份已识别但没有权限 | 账户状态、渠道权限、来源限制 |
| 404 | 地址或资源不存在 | Base URL、路径、模型 ID |
同一个服务商可能返回自定义错误码，因此还要结合响应体和 request ID 判断。不要把完整密钥、用户 prompt 或响应中的敏感信息直接写入日志。
401：先检查 Authorization
OpenAI 兼容接口通常要求在请求头中发送 Authorization: Bearer YOUR_KEY。常见错误包括多写了引号、把环境变量名称当成值、Key 前后带空格，或把服务商后台的登录密码当成 API Key。
curl -i https://你的中转站域名/v1/models \
-H "Authorization: Bearer $API_KEY"
如果返回 401，重新复制 Key 并确认它属于当前账户和当前 Base URL。服务端读取环境变量时，可以只记录 Key 的前 4 位和后 4 位用于核对，绝不要打印完整值。
403：认证成功但权限不足
403 常见于账户被冻结、余额或风控状态异常、模型渠道未开通，以及服务商限制来源 IP、Referer 或区域。先登录服务商控制台查看账户通知，再确认该模型是否需要单独申请。
如果浏览器请求 403 而命令行正常，可能是前端跨域或来源策略导致。把密钥放在服务端代理中，浏览器只调用自己的后端接口，通常比把 Key 暴露在前端更安全。修改权限后要等待缓存或策略同步，再用新的 request ID 测试。
404：地址和模型 ID 两条线排查
404 可能是 Base URL 多写或少写了 /v1，也可能是请求路径与服务商文档不一致。例如文档要求 /v1/chat/completions，代码却拼成了 /chat/completions。另一种常见情况是模型 ID 写错、大小写不一致，或该模型已下线。
把最终请求 URL 打印出来（隐藏 Key），再用 /v1/models 或服务商提供的模型列表接口确认可用 ID。不要直接把官网模型名称当成 API 的 model 参数；列表中的 slug 才是通常需要提交的值。
推荐的三步定位流程
- 用
curl -i绕过业务代码，记录状态码、响应体和 request ID； - 核对 Base URL、路径、Authorization 和模型 ID 四个字段；
- 在服务商控制台确认账户余额、模型权限和安全策略，再进行一次最小请求。
测试时使用最短 prompt 和低成本模型，避免反复排查造成不必要的费用。不同中转站的路径、错误字段和权限规则可能不同，最终以服务商当前文档为准。