硅基流动 401 鉴权失败怎么排查：官方错误码与检查顺序

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

硅基流动的官方错误码表里，401 对应的原因只写了一句话：API Key 没有正确设置。这句话看着简单，实际含义比”key 填错了”要宽——鉴权头的写法、请求发到了哪个基址、这把 key 属于哪个账户、客户端有没有把 key 传进去，任何一环断掉都会落在这一条上。所以排查 401 的正确姿势不是反复复制粘贴 key，而是先把错误响应原样打印出来确认它真是 401，再沿着”头 → 地址 → 账户归属 → 最小复现 → 网络环境”这条线一层层剥。更要紧的是别把邻居错误当成 401 来治：官方把账户欠费划给 402、把权限不足（最常见的原因是该模型需要实名认证）划给 403、把限流划给 429，这几种情况改多少次 key 都没用。

先确认它真的是 401，而不是别的码

官方给出的通用排查步骤里，第一步就是把错误码和 message 打印出来。这一步很多人跳过，直接看客户端界面上那句红字提示，而客户端往往把不同的失败合并成一句”鉴权失败”或”连接异常”。

硅基流动的错误响应是结构化的，官方给的示例形状是这样：

{"code":20012,"message":"Model does not exist. Please check it carefully.","data":null}

三个字段：code 是平台自己的错误码，message 是给人看的说明，data 在报错时为 null。注意平台错误码（示例里的 20012）和 HTTP 状态码不是一回事，两者要分开看——你要判断是不是 401，看的是 HTTP 状态码；你要知道具体哪里错了，看的是 message。

官方错误码表里各个状态码的分工是这样划的（以官方文档为准）：

• 400：参数不正确，按 message 修正非法的请求参数
• 401：API Key 没有正确设置
• 402：账户欠费，充值后重试
• 403：权限不够，最常见的原因是该模型需要实名认证；其他情况看 message
• 429：触发了 rate limits，按 message 判断是 RPM、RPD、TPM、TPD、IPM、IPD 中的哪一项（官方错误码表列的是这六项，与下文那份七项指标清单不是同一个列表）
• 503 / 504：服务负载较高，稍后再试；对话与 TTS 请求可以尝试改用流式输出
• 500：未知错误，联系官方排查

把这张表摆在面前，401 的边界就清楚了：它只管”你是谁”这件事，不管”你有没有钱""你够不够格用这个模型""你调得太快没有”。如果你看到的其实是 402 或 403，那么问题在账户状态而不在密钥本身，请转到对应的路子上去，别在密钥页面反复重建。

第二步：检查鉴权头本身怎么写

官方文档里写明的鉴权方式是在请求头里带：

authorization: Bearer <你的 apikey>

这一行有几个容易出岔子的地方，都属于”API Key 没有正确设置”的范畴：

• Bearer 和 key 之间是一个空格，整段是 Bearer 加上密钥本身，不是只填密钥
• key 两侧不要带引号。从网页复制到配置文件时，很多编辑器会顺手补一对引号，配置解析后引号进了请求头
• key 里不要混进换行或首尾空格。从终端里复制多行文本、或者从聊天工具里复制时最容易带进不可见字符
• 别把占位符原样提交。示例里的 <你的 apikey> 是占位写法，尖括号不属于密钥内容

密钥本身在控制台的「API 密钥」页面新建。如果你连控制台都进不去，那问题在登录环节而不在鉴权环节——官方目前支持的登录方式是短信登录与邮箱登录。

至于密钥的格式前缀是什么、密钥有没有有效期、一个账户能建多少把、是否支持按 IP 白名单限制调用来源、密钥泄露后平台会不会自动吊销——这些官方文档里没有找到相关说明，别按其他平台的习惯去想当然。密钥怎么保管、怎么轮换、怎么避免进代码仓库，属于跨厂商的通用课题，可以看API Key 安全管理那篇。

第三步：确认请求确实发到了硅基流动

鉴权头没问题，但请求根本没发到硅基流动，一样过不了鉴权。这在用 OpenAI 生态的库和客户端时特别常见，因为硅基流动兼容 OpenAI 与 Anthropic 的对话协议，大语言模型可以直接用 OpenAI 官方库调用，代价就是不改地址也能跑起来、只是跑去了别人家。

官方给的 API 基址是 https://api.siliconflow.cn/v1，聊天端点是 https://api.siliconflow.cn/v1/chat/completions。官方 Python 示例里，客户端初始化是把 base_url 显式指向前面那个基址、api_key 传硅基流动的密钥（示例还要求 Python 3.7.1 或更高版本）。所以检查顺序是：

1. 配置里的 base_url / 接口地址那一栏，值是不是硅基流动的基址
2. 这一栏改完有没有真正生效——部分客户端改完配置后需要重启才会生效，具体以该客户端自己的说明为准
3. 环境变量里有没有一份旧的同名配置，把你在界面上填的那份盖掉了

官方文档没有单独说明”漏填基址时会返回哪个状态码”，所以这里不要凭状态码反推，直接去看配置值本身更可靠。另外，官方文档写明的鉴权头形式是 authorization: Bearer；Anthropic 风格客户端惯用的另一种密钥头是否同样被接受，官方文档未说明，按文档写明的这一种来最稳妥。接入的完整步骤可以对照硅基流动 API 接入。

第四步：核对这把 key 属于哪个账户

同一个人手里有多把 key、多个账号，是 401 和”看起来像 401”的问题里最隐蔽的一类。官方文档在两个地方专门提到过这种账户与密钥错配：

• 已经充值成功，调用却仍提示余额不足：官方给的排查方向是确认 api_key 是否与刚刚充值的那个账户匹配；另外也可能存在网络延迟，等几分钟再重试
• 专属实例出现 429：官方要求先确认是否调用了专属实例的正确模型名、api_key 是否与专属实例匹配

这两条讲的都是同一件事：密钥是绑定到具体账户（或具体实例）的，用错了账户的密钥，报出来的症状未必写着”密钥错误”。所以当你确认头没写错、地址没填错、key 也是刚复制的，下一步就该回控制台看这把 key 是在哪个账号下面生成的，以及你充值、实名、开专属实例的是不是同一个账号。

顺带说一个和 401 相邻但归属不同的情况：账户没有完成实名认证时，受影响的是充值与开票，并且实名后才能使用全部免费模型；而模型层面的权限不足，官方是划在 403 而不是 401 里的。也就是说，实名与否不会让你的密钥变成”没设置”，它会让你在某些模型上撞 403。

第五步：用 curl 做最小复现，再关掉代理

官方的通用排查步骤后面三条，本质上是在做”变量消元”：

1. 用 curl 复现——把客户端、SDK、插件全部摘出去，只留一个裸请求。如果 curl 能通而客户端不通，那问题在客户端怎么组装请求头，不在密钥
2. 换一个模型试——如果只有某个模型失败、其他模型正常，那更可能是模型名或模型权限的问题，而不是鉴权
3. 如果开了代理，关闭代理再试——这一条是官方明写的排查项。代理链路上的中间层可能改写或丢掉请求头，鉴权头一旦在半路被动过，服务端看到的就是一个没带 key 的请求

这三步的顺序不能颠倒。先 curl 复现，你才知道要不要继续往客户端里查；先换模型，你才知道是全局失败还是单模型失败。跳过复现直接改配置，很容易在两个变量之间来回横跳。

排除 401 之后，最容易接着撞上的两个码

401 修好之后，接下来最常遇到的是 429 和 403，这两个的判定逻辑值得提前知道，免得又误判成鉴权问题。

429 这边，硅基流动一共有七种限流指标——RPM、RPH、RPD、TPM、TPD、IPM、IPD——任意一种先达峰就会触发，不需要全部达标。官方举过一个例子：假设某模型的每分钟请求数和每分钟 token 数各有上限，你在一分钟内发满了请求数，即使 token 数远远没用完，限流照样会触发。还有两个结构性事实值得记住：限流是定义在用户账户级别的，不是 api key 维度，所以多建几把 key 并不能把额度做大；每个模型单独设置限额，一个模型超限不影响其他模型。官方给出的 429 处理方式是等待后重试，并推荐使用指数退避。细节见硅基流动速率限制与跨平台的429 通用处理。

403 这边，官方明说最常见的原因是该模型需要实名认证，其他情况看 message。这里还牵扯到一条容易忽略的命名规则：部分模型同时提供免费版与收费版，免费版按原名称命名，收费版在名称前加 Pro/ 前缀；免费版的限额是固定值，收费版的限额随账户用量级别变化。所以当你把模型名从原名换成带前缀的那个之后行为变了，那是模型换了，不是密钥出了问题。

最后：把排查过程留痕

401 这类问题最耗时间的地方，往往不是找不到原因，而是改了七八个地方之后已经说不清哪一次改动起了作用。建议每次只动一个变量，并且把三样东西记下来：HTTP 状态码、code 与 message 原文、你这次改了哪一项配置。官方通用排查步骤的第一条之所以是”打印错误码与 message”，正是因为后面每一步都要靠它来判断该不该继续往下走。

还有一个心态上的提醒：不要一遇到鉴权失败就先去重建密钥。删旧建新可能牵连到其他还在用这把密钥的项目，把一个问题变成一串问题，而按上面的顺序走一遍，多数情况下在第二步或第三步就能定位。真到了每一步都排除干净、curl 裸请求也稳定复现 401 的地步，再拿着完整的错误码与 message 走官方支持渠道，比自己反复猜要快得多。