智谱近期正式发布 GLM-5.2，我第一时间把项目里的 model 字段从 glm-4 换成了 glm-5.2，结果十分钟内连续吃了三种不同的报错。422、401、429 轮着来，一度以为是自己环境炸了。折腾了大半天，把三种报错的原因全摸清楚了。如果你也是升级踩坑的，直接往下看对应的错误码，大概率能省你几个小时。

简单说结论：422（实际返回 400）是因为 GLM-5.2 的 message 结构有变更，旧写法会触发字段校验失败；401 是新旧 API Key 体系混用导致鉴权不通过；429 是免费配额和付费配额可能共享计数器，免费额度耗尽后付费请求也会被限流。三个问题互相独立，但升级当天很容易同时撞上。

为什么会出现这些问题

GLM-5.2 上线做了几个不向后兼容的改动（至少从我实测来看是这样）：

1. messages 数组的第一条 role 校验更严格了，以前能混过去的写法现在直接 400
2. 控制台新生成的 Key 和老 Key 的鉴权走了不同的验证路径
3. 据我实测，免费模型（glm-4-flash）和付费模型（glm-5.2）的 QPS 计数器似乎是共享的，不是隔离的，具体机制以官方文档为准

我一开始以为是 key 填错了，反复检查了三遍。后来才发现这三个问题各有各的坑。

graph TD
 A[调用 GLM-5.2 API] --> B{返回什么错误码?}
 B -->|400/422 + code 1214| C[message 结构问题]
 B -->|401 + code 1101| D[API Key 鉴权问题]
 B -->|429 + code 1302| E[配额限流问题]
 C --> F[修复 role 字段格式]
 D --> G[重新生成 Key]
 E --> H[分离免费/付费调用 或 加退避重试]

方案一：修复 422 / 400 — message 结构变更

实际返回的 HTTP 状态码是 400，但语义上是"请求体不可处理"，所以很多人叫它 422。完整报错长这样：

{"error": {"code": "1214", "message": "messages[0].role must be user or system"}}

原因是 GLM-5.2 对 messages 数组第一条的 role 做了强校验。以前我习惯在 messages 开头塞一条 assistant 作为 few-shot 示例，GLM-4 对此校验较宽松（或未严格执行），5.2 直接拒绝了。

错误写法（GLM-4 可能容忍，5.2 不行）：

messages = [
    {"role": "assistant", "content": "示例回答"},
    {"role": "user", "content": "你好"}
]

正确写法：

messages = [
    {"role": "system", "content": "你是一个助手"},
    {"role": "user", "content": "你好"}
]

另一个容易踩的坑：如果你用了 human 或 AI 这种 LangChain 风格的 role 名，也会触发 1214。GLM-5.2 只认 system、user、assistant 三种，拼写必须完全匹配。

把 messages 格式改对之后，这个报错就消失了。没什么花哨的，就是字段校验变严了。

方案二：修复 401 — 新旧 Key 体系混用

报错原文：

{"error": {"code": "1101", "message": "Invalid Authorization"}}

这个坑比较隐蔽。我的 Key 是去年在控制台生成的，格式是 {id}.{secret} 两段式，一直用得好好的。但 GLM-5.2 上线当天，我在控制台看到提示说"建议重新生成 API Key 以支持新模型"，就顺手生成了一个新的。

问题来了：我本地 .env 里还是老 Key，但 CI 环境用的是新 Key。据我实测，老 Key 调 glm-4 没问题，调 glm-5.2 就返回 1101（新旧 Key 体系的具体差异未见官方变更说明，以下排查方法供参考）。

排查方法很简单，用 requests 直接打一个裸请求：

import requests

headers = {"Authorization": "Bearer YOUR_KEY"}
data = {
    "model": "glm-5.2",
    "messages": [{"role": "user", "content": "test"}]
}
resp = requests.post(
    "https://open.bigmodel.cn/api/paas/v4/chat/completions",
    headers=headers,
    json=data
)
print(resp.status_code, resp.text)

如果返回 1101，去控制台重新生成一个 Key，确认格式还是 id.secret，然后替换掉所有环境变量里的旧值。我那天光是找哪个环境用的哪个 Key 就花了 40 分钟，挺烦人的。

还有一个细节：Authorization 头应始终使用标准的 Bearer {key} 格式。有人习惯写成 Token {key} 或者不加 Bearer 前缀，这与 Bearer Token 标准相悖，GLM-5.2 会直接拒绝，请始终使用标准 Bearer 格式。

方案三：修复 429 — 免费配额与付费配额共享计数

报错原文：

{"error": {"code": "1302", "message": "Requests rate limit reached"}}

这个是最让我困惑的。我明明是付费用户，怎么还被限流？

后来我发现：我的项目里同时在调 glm-4-flash（免费）和 glm-5.2（付费）。据我实测推断，两者可能共享同一个账号的 QPS 计数器，具体机制以官方文档为准。glm-4-flash 的免费配额本身就低，我的一个定时任务每分钟打 20 次 flash，把整个账号的请求窗口吃满了，导致 glm-5.2 的请求也被 429。

解决办法有三个层次：

最快的临时方案：给 429 加指数退避重试

import time
import requests

# 以下 call_api() 为示意函数，请替换为你实际的 API 请求逻辑
def call_api():
    headers = {"Authorization": "Bearer YOUR_KEY"}
    data = {
        "model": "glm-5.2",
        "messages": [{"role": "user", "content": "test"}]
    }
    return requests.post(
        "https://open.bigmodel.cn/api/paas/v4/chat/completions",
        headers=headers,
        json=data
    )

for attempt in range(5):
    resp = call_api()
    if resp.status_code == 429:
        time.sleep(2 ** attempt)
    elif resp.status_code == 200:
        # 请求成功，处理响应
        break
    else:
        # 401、500 等其他错误不应静默重试，直接抛出
        raise RuntimeError(f"API 请求失败：{resp.status_code} {resp.text}")

注意：time.sleep(2 ** attempt) 在 attempt 从 0 开始时，五次重试的等待时间依次为 1、2、4、8、16 秒，最长累计等待 31 秒。对于 401、500 等非限流错误，代码会直接抛出异常而不是静默重试。

中期方案：把免费模型和付费模型的调用拆到不同的 API Key 下。控制台可以生成多个 Key，每个 Key 有独立的 rate limit 计数。

长期方案：如果你的项目同时用多家模型（GLM + Claude + GPT），可以考虑走聚合 API 网关来做统一的限流和 fallback。像 OpenRouter 这类平台可以在网关层做 429 自动重试和模型降级，不用自己在业务代码里写一堆 retry 逻辑。

三种报错速查表

错误码	HTTP 状态	原因	修复动作	耗时
1214	400	messages[0].role 非 user/system	改 role 字段	2 分钟
1101	401	旧 Key 对新模型鉴权失败	控制台重新生成 Key	5 分钟
1302	429	免费+付费可能共享 QPS 计数器	拆 Key / 加退避 / 走网关	30 分钟

常见问题 FAQ

Q: GLM-5.2 的 API 地址和 GLM-4 一样吗？

一样，endpoint 路径没有变化，model 字段改成 glm-5.2 就行。

Q: 我用 zhipuai SDK 调用报 ModuleNotFoundError 怎么办？

升级到最新版：pip install --upgrade zhipuai。老版本的 SDK 可能没有 GLM-5.2 的模型校验通过，虽然理论上 model 只是个字符串参数，但据反馈某些版本会在客户端做预校验（具体受影响版本范围未经系统测试，建议直接升级到最新版以规避）。

Q: 429 限流的具体 QPS 上限是多少？

官方目前未公开精确数字，请以官方文档或联系智谱商务为准。根据我的个人实测推断，免费账户大概在 5–10 QPS 附近开始触发限流，付费账户会高一些，但这些数值仅供参考，不代表官方规格，且可能随套餐调整而变化。如需更高 QPS，建议联系智谱商务单独提额。

Q: 老的 API Key 还能用吗？

据我实测，调 glm-4 系列目前还能用，但调 glm-5.2 会报 1101。建议统一换成新生成的 Key，省得后面哪天老 Key 全面失效又要改一轮。

Q: stream 流式输出在 GLM-5.2 上有变化吗？

解析方式没变，还是 chunk.choices[0].delta.content。但我注意到 5.2 的流式响应最后一个 chunk 的 finish_reason 从 stop 变成了 end_turn——此为个人观察，未经官方确认。需要注意的是，OpenAI 兼容接口规范中标准值为 stop，end_turn 是 Anthropic Claude 的惯用值，两者混用可能引起混淆。如果你的代码里有判断 finish_reason 的逻辑，建议同时兼容 stop 和 end_turn 两个值，以防万一。

我的最终选择

三个问题修完之后，GLM-5.2 跑起来还挺稳的。一开始我是拒绝升级的，毕竟 GLM-4 用得好好的，但 5.2 在长文本理解上确实有明显提升，我那个文档摘要的场景准确率高了不少。

目前我的做法是：开发阶段用 glm-4-flash 省钱调试，生产环境用 glm-5.2，两个模型分别绑不同的 API Key 避免 QPS 互相影响。retry 逻辑写了一个通用的 decorator，碰到 429 自动退避，碰到 401 直接报警通知我去换 Key。

如果你也在升级时踩了这些坑，希望这篇能帮你少走点弯路。有其他报错欢迎评论区贴出来，我看到会回。