GLM API 常见报错排查：密钥、模型名与配额

2026-07-27

数据截至 2026-07，价格与限额以各官网为准。

GLM API 的报错里，真正由”代码写错”引起的其实是少数。绝大多数卡住新手的问题集中在三个地方：base_url 或密钥没配对、模型名抄了过期的教程、以及把上下文窗口、最大输出、订阅套餐额度、按量计费这几件事混成一件事。把这三类先排掉，剩下的问题通常十分钟内能定位。

先承认一个很常见的误解：很多人一遇到报错，第一反应是去搜”GLM 错误码 xxxx 是什么意思”，然后照着某篇几个月前的博客对号入座。这条路经常不灵——一是智谱模型和平台迭代很快，错误码的含义和触发条件都可能调整；二是同一个现象（比如”调用失败”）在不同层可能有完全不同的原因。所以这篇不给你一张”错误码对照表”，而是给一套排查顺序：从外往里剥，先确认能不能连上、再确认身份对不对、然后确认模型名和参数、最后才怀疑自己的业务逻辑。至于每个错误码的确切含义，以 docs.bigmodel.cn 上当次看到的错误码文档页为准，别信我也别信任何三方博客的转述。

第一层：base_url 有没有填对

这是从别的服务迁移过来的人最容易漏掉的一步。GLM 做了 OpenAI 兼容层，所以你可以直接用 openai 这个 Python 包调用，但兼容的是接口形态，不是地址。如果你是把之前接 OpenAI 或者其它服务的代码改过来，很容易只改了 api_key 和 model，忘了改 base_url，结果拿着智谱的密钥去撞别人家的端点，那当然认不出来。

官方 OpenAI 兼容文档给出的通用 Chat 地址是：

https://open.bigmodel.cn/api/paas/v4/

最小可运行的调用长这样：

# pip install --upgrade "openai>=1.0"
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("ZAI_API_KEY"),
    base_url="https://open.bigmodel.cn/api/paas/v4/",
)

completion = client.chat.completions.create(
    model="glm-4.7-flash",   # 免费模型，先用它跑通链路最省事
    messages=[{"role": "user", "content": "你好，请自我介绍一下。"}],
)
print(completion.choices[0].message.content)

还有一个容易踩的分叉：网上有些讲把 GLM 接进 Claude Code、Cline 这类编程工具的教程，用的是编程场景的专用地址 https://open.bigmodel.cn/api/coding/paas/v4。这个地址在第三方教程里出现得很多，但我没在官方那篇 OpenAI 兼容介绍页上逐字核到，所以这里只作为线索提一句：如果你在做通用对话调用却抄了编程场景的地址（或者反过来），出现的现象就是路径对不上、请求走不通。两个地址分别用在什么场景，以官方文档当前页面为准，别互相套用。

如果你不想折腾兼容层，也可以直接用官方原生 SDK：

# pip install zhipuai
from zhipuai import ZhipuAI

client = ZhipuAI(api_key="your-zhipuai-api-key")

response = client.chat.completions.create(
    model="glm-4.7-flash",
    messages=[{"role": "user", "content": "你好，请自我介绍一下。"}],
)
print(response.choices[0].message.content)

原生 SDK 的好处是地址由包内部维护，你不用自己拼 base_url，也就少了一整类出错可能。代价是换服务商时迁移成本高一点。两条路都能跑通，选一条走到底，别在一个项目里混着用——混着用最容易出现”我明明改了地址怎么还是老样子”这种自己骗自己的情况。

第二层：密钥到底有没有被读到

“鉴权失败”这个现象，我见过的原因里排第一的不是密钥本身错，而是密钥根本没进到进程里。官方建议把密钥放在环境变量 ZAI_API_KEY 里，代码用 os.getenv("ZAI_API_KEY") 读。这个做法本身没问题，但它引入了几个静默失效的可能：

变量名拼错了。ZAI_API_KEY 和 ZHIPU_API_KEY、ZAI_APIKEY 长得都挺像，os.getenv 拿不到就返回 None，不会报错，一路带着 None 走到请求那一步才炸。
环境变量只在某个终端窗口里设过，换了个窗口、或者交给 IDE、systemd、Docker 起进程，那个变量压根不在。
用 .env 文件但忘了真正加载它（比如没装/没调用 python-dotenv）。
复制密钥时带上了首尾空格或者换行符。

排查动作只有一个，先别改代码逻辑，先打印：

import os
k = os.getenv("ZAI_API_KEY")
print(type(k), len(k) if k else None, repr(k[:6]) if k else None)

打出来是 None 就说明是环境问题，不是密钥问题；能打出长度和前几位，再去平台上比对是不是当前有效的那一把。别把完整密钥打印到日志里，更别提交进仓库——密钥泄露之后，别人拿去消耗的是你的额度。开发环境和生产环境建议各建一把，出事时能单独吊销一把，不至于全盘换。

密钥在哪建？登录 bigmodel.cn 或 open.bigmodel.cn（这两个域名并存、指向同一个平台），进用户中心的 API Keys / 密钥管理页面创建。文档站是独立的 docs.bigmodel.cn，那里没有密钥入口，别在文档站上找。

第三层：模型名，一字之差就是两回事

这是 GLM 特有的一个高频坑，值得单拎出来说。智谱当前在架的模型很多，命名规律又比较密集，抄错一个字符就会得到”模型不存在”或者”这个模型不是我以为的那个”。截至 2026-07，官方模型概览页上能查到的文本模型大致是这么几组：

GLM-5 系列：glm-5.2（上下文 1M、最大输出 128K）、glm-5.1、glm-5、glm-5-turbo（后三者上下文 200K、最大输出 128K）。
GLM-4.7 / 4.6 系列：glm-4.7、glm-4.6，上下文 200K、最大输出 128K；另有 glm-4.7-flashx 这个轻量高速版。
GLM-4.5 系列：glm-4.5、glm-4.5-air、glm-4.5-airx，上下文 128K、最大输出 96K。
长上下文：glm-4-long，上下文 1M，但最大输出只有 4K。
免费档：glm-4.7-flash（200K / 128K）、glm-4-flash-250414（128K），官方文档明确标为免费模型。

最要命的一对是 glm-4-flash-250414 和 glm-4-flashx-250414。中间多一个字母 x，前者是免费模型，后者是付费的轻量版（128K 上下文、最大输出 16K）。抄教程时手滑多打或者少打一个 x，跑起来一切正常、没有任何报错，只是账单上悄悄开始计费。同理，glm-4.7-flash 和 glm-4.7-flashx 也是这个关系。凡是想用免费档的，写完模型名务必回头一个字符一个字符核一遍。

还有一个”报错但其实不是报错”的情况：glm-4.5-flash 已经在 2026-01-30 下线了，但请求不会失败，会自动路由到 glm-4.7-flash。所以如果你发现返回的表现跟旧教程描述的对不上，先别怀疑自己，可能只是你调的那个名字已经被路由到别的模型上了。新代码里直接写 glm-4.7-flash 更清楚。

抄来的模型名跑不通时，正确动作不是去搜别人的清单，而是打开 docs.bigmodel.cn 的模型概览页看当前在架列表——智谱这几年迭代的速度，让任何静态清单（包括这篇里的）都有过期风险。

第四层：上下文、最大输出与”截断”

有一类现象不会抛异常，但结果明显不对：输出突然断在半句话上，或者长文档喂进去直接被拒。这通常不是 bug，是撞了两个不同的天花板，很多人会把它们混为一谈：

上下文窗口：一次请求里输入加输出能占用的总长度上限。
最大输出：单次回复最多能生成多少 token，是上下文窗口里的一个子额度。

看回上面那份清单就明白为什么要分开看。glm-4-long 上下文有 1M，听起来很夸张，但最大输出只有 4K——它的定位是”读很长的东西，然后给一个短结论”，你要它一口气写两万字的稿子，它做不到，这不是报错，是设计如此。反过来 glm-4.5 上下文 128K、最大输出 96K，能吐的比例就高得多。

所以遇到输出被截断，排查顺序是：先看你调的模型最大输出是多少，再看你有没有显式设置输出长度参数（很多 SDK 有默认值，默认值通常远低于模型上限），最后才考虑是不是提示词让模型自己提前收尾了。喂长文档报错则反过来，先估算输入长度是不是逼近甚至超过上下文窗口，超了就得换更大窗口的型号，或者自己先做切分和摘要。

顺带说一句计费单位，它会影响你对”我到底用了多少”的判断：智谱官方口径是”其它模型均按照每千 tokens 为单位计费”，而横评文章为了对齐一般会换算成每百万 tokens。换算方向别搞反，1 元／千 tokens 等于 1000 元／百万 tokens，看到某个数字觉得贵得离谱或者便宜得离谱时，先确认单位。目前能核到官方原文逐字表述的单价是 GLM-4.5：输入 0.8 元／百万 tokens、输出 2 元／百万 tokens。其它型号的具体单价，官网定价页是前端渲染的，请自行打开 bigmodel.cn/pricing 或 open.bigmodel.cn/pricing 核对当前数字，别照抄任何二手清单。

第五层：配额、限速与”套餐额度用完了”

请求偶尔失败、高峰期失败率上升、批量跑一半突然大面积失败——这类现象大概率跟并发和配额有关，而不是代码。这里有几件事需要分清楚：

免费不等于无限。 免费档模型（glm-4.7-flash、glm-4-flash-250414）是不收 token 费用，但仍然受并发和速率限制约束。具体的 RPM／TPM 数值我没能在官方页面上核实到，所以这里不给数字，你需要以控制台和官方文档当次展示的限制为准。工程上的做法很简单：别指望免费档扛住高并发，写重试和退避逻辑，串行或者小并发跑，失败了等一会儿再试而不是立刻重发（立刻重发只会让情况更糟）。

新用户赠送额度不要当成稳定事实。 网上流传着好几种”注册送多少 token”的说法，口径互相打架，我在官方页面上没能逐字核实到任何一个版本，所以这篇不引用具体数字。你要知道自己账户里有多少，唯一可靠的办法是登录后看账户页面的实时展示。真正稳定、可以规划的是免费档模型本身长期免费这件事——不依赖赠送额度也能零成本跑通链路。

订阅套餐和按量计费是两套账。 智谱另有面向编程场景的订阅套餐体系（Lite / Pro / Max 等），它的额度限制方式是”每 5 小时 / 每周”这种时间窗口，而不是纯 token 计费。这就带来一个很典型的困惑：你订了套餐，用编程工具跑着跑着突然被限，去查按量计费的余额发现还有钱——两者压根不是一个池子。套餐的价格、额度换算和适用范围我没能在官方原文里逐字核实，所以不在这里给数字，具体请看 bigmodel.cn/special_area 或 open.bigmodel.cn/special_area 当前页面。

如果你的场景是离线批量处理（比如给一批历史数据打标、批量摘要），别用同步接口硬扛并发限制。官方的 Batch API 明确写了”只需五折费用”，异步跑既能压成本又能避开同步限速，属于该用的时候一定要用的东西。

什么时候该怀疑自己的代码

前面五层都排掉之后，才轮到业务代码。这里列几个高频但不属于平台问题的情况：

messages 结构不合法：角色拼错、content 传了非字符串、消息数组为空。兼容层对结构的要求跟 OpenAI 一致，照着标准格式写就行。
流式和非流式的返回结构不一样：开了 stream=True 还按非流式去取 choices[0].message.content，取到的自然是空。流式要遍历 chunk 取增量字段。
用量统计口径：流式与非流式下 token 用量字段的呈现可能不完全相同，如果你要精确记账，以实际返回内容里的字段为准，别默认两种模式一模一样。
超时设置太短：长上下文请求本来就慢，客户端默认超时可能不够，表现出来是”超时”，其实服务端还在正常生成。

不适用与局限

说几句诚实的话。第一，这篇给的是排查方法和当次核实到的清单，不是错误码字典——智谱的错误码含义请以官方文档为准，我不复述任何未核实的映射关系。第二，模型清单和上下文规格是截至 2026-07 的核实结果，智谱迭代很快，几个月后极可能变化，所有具体数字都建议在动手前打开官网当次确认。第三，价格方面，我只引用了能核到官方原文的 GLM-4.5 单价和 Batch 五折这两条，其它型号的价格网上流传的版本很多，但官网定价页是前端渲染的，我无法逐字核实，所以一律不写具体数字——你在别处看到言之凿凿的完整价格表时，也建议留个心眼。

小结

排查 GLM API 报错，顺序比知识更重要：先确认 base_url 对不对，再确认密钥有没有真的读进进程，然后逐字符核对模型名（glm-4-flash-250414 与 glm-4-flashx-250414 只差一个 x，一个免费一个付费），接着分清上下文窗口和最大输出这两个不同的天花板，最后才看配额、限速和套餐额度。免费档能长期用，但不是无限并发，批量任务用 Batch API 更合适。所有具体数字都以官网当次页面为准，包括这篇里写的——这不是免责套话，是智谱这个迭代速度下最省时间的做法。