通义千问 API 报错排查：鉴权、端点、模型名、区域四类

2026-07-27

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

通义千问 API 调不通，绝大多数落在四个地方：鉴权链路没打通、base_url 端点填错、模型名写了个平台上不存在的代号、区域选错导致密钥和端点对不上。这四类的报错信息长得很像，都可能表现为一句语焉不详的失败响应，所以与其对着错误码逐个查含义，不如按固定顺序把这四类各自排掉，通常十几分钟就能定位。

一个常见的误解是：既然百炼提供 OpenAI 兼容模式，那把手头的 OpenAI 代码改个 key 就一定能跑。兼容的是接口协议，不是账号体系和地域策略。密钥属于哪个账号、端点属于哪个区域、模型代号在这个区域是否在售，这三件事都不由 SDK 负责，全得你自己配对。下面按排查成本从低到高展开。

第一类：鉴权链路，先怀疑环境变量而不是密钥本身

大多数”鉴权失败”其实跟密钥有没有效关系不大，而是那串字符压根没被读进请求里。官方文档建议把密钥配置成环境变量使用，避免明文写进代码，示例里读的是 DASHSCOPE_API_KEY 这个名字。这个建议本身没问题，但它引入了一个新的失败点：变量到底有没有进当前进程。

排查动作很直白，在发请求之前先把值打出来看一眼：

import os
key = os.getenv("DASHSCOPE_API_KEY")
print(type(key), len(key) if key else "None")

打出 None 就说明问题在环境，不在阿里云。常见原因有几种：变量写在 .env 里但代码没加载它；在终端里 export 之后又新开了一个终端窗口跑程序；IDE 的运行配置和你手动跑的 shell 不是同一套环境；服务部署成 systemd 服务时没把变量注入到服务单元里。这几种情况在本地能跑、上服务器就挂，非常典型。

打印出来长度正常，再确认密钥本身。百炼的 API-KEY 在阿里云百炼控制台创建和查看，入口是 https://bailian.console.aliyun.com/，密钥管理页面能看到当前账号下已有的 key。这里要注意首次开通这个动作：官方说明写的是，第一次访问控制台会弹出服务协议，阅读并同意后才自动开通百炼服务；如果没弹协议，说明这个账号之前已经开通过。有人在一个从没开通过服务的账号里到处找 API-KEY 入口，找不到就以为是页面改版，其实是服务还没开。

还有一类隐蔽的错配：用了 RAM 子账号。官方明确说明主账号与其 RAM 子账号共享同一份免费额度、统一计算消耗，但共享额度不等于权限自动齐全，子账号的授权策略是否覆盖了你要调的能力，得回到访问控制里确认。如果你的 key 是同事给的，先问清楚它属于主账号还是子账号。

密钥安全这块顺带提一句，key 一旦泄露别人就能消耗你的额度，别提交进代码仓库，也别放前端。这部分的通用做法可以看API Key 安全管理：泄露风险与最小权限实践。

第二类：base_url 填错，这是”鉴权失败”最爱伪装的样子

如果你从别的平台迁移代码过来，只改了 api_key 忘了改 base_url，那就是拿着百炼的密钥去撞别人家的端点，对方当然认不出来，返回的往往还是一句鉴权错误——这就是为什么第一类和第二类必须连着查。

百炼 OpenAI 兼容模式的端点，官方文档里目前存在两套表述，这一点需要如实说明。一套是被广泛使用的经典端点：中国内地（北京）是 https://dashscope.aliyuncs.com/compatible-mode/v1，新加坡国际站是 https://dashscope-intl.aliyuncs.com/compatible-mode/v1。另一套是官方较新文档页里出现的按业务空间区分的端点格式，形如 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1，新加坡、日本东京、德国法兰克福是同样的构造方式，只有美国弗吉尼亚给的是 https://dashscope-us.aliyuncs.com/compatible-mode/v1 这种不带 WorkspaceId 的形式。其中 {WorkspaceId} 是百炼控制台业务空间详情页可以查到的空间 ID。

这两套端点的关系、以及各自适用于什么场景，官方文档没有给出一句能彻底消除歧义的说明，看起来像是平台正在做地域端点的迁移。实践建议是：不要凭记忆或凭旧教程写 base_url，以你登录控制台当时那一页显示的地址为准。如果你用了带 WorkspaceId 的新格式却把占位符原样留在字符串里没替换，或者替换成了一个不属于你的空间 ID，得到的同样是连不上或没权限。

最小可用的调用长这样，官方文档给的示例结构就是这个形态：

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 按你所在区域/控制台显示替换
)

completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "你是谁？"},
    ],
)
print(completion.model_dump_json())

跑通这段之前，别急着往里加流式、函数调用、多模态。把最小闭环打通，再逐个加特性，出问题时才知道是哪一步引入的。完整接入流程可以对照通义千问 Qwen API 怎么接入？百炼平台密钥与 SDK 调用。

第三类：模型名，新旧两套命名同时在售是最大的坑

这是通义千问特有的、比别家更容易出错的一处。截至 2026-07 观察到的情况是，经典命名和 Qwen3 新系列命名并存在售：前者是 qwen-max、qwen-plus、qwen-flash、qwen-turbo、qwen-long 这几个不带版本号的名字，后者是 qwen3-max、qwen3.7-max、qwen3.7-plus、qwen3.5-flash、qwen3.6-plus、qwen3.6-flash 这类带具体版本号的名字。

由此产生的典型错误有三种。

一是抄了半年前的教程，里面写的版本号型号可能已经下架或改名。带小数版本号的代号迭代很快，教程里的 qwen3.x-* 不一定还在当前模型列表里。

二是自己拼版本号。看到有 qwen3.5-flash 和 qwen3.7-plus，就顺手推断存在 qwen3.7-flash 或 qwen3.5-plus——平台上有没有这个组合，只有模型广场页面说了算，推断出来的代号大概率直接报模型不存在。

三是把区域在售清单当成全局清单。中国内地站与国际站的模型上架情况不一定完全一致，在内地能调的名字换到新加坡端点未必存在。

排查方法只有一条靠谱：打开百炼控制台的模型广场，看当前账号、当前区域下这个模型是不是真的在列，然后原样复制它的代号，不要手敲。手敲最容易在小数点和连字符上出错。

顺带说一个会伪装成”模型名错误”的问题：计费方式。qwen-plus、qwen-flash 以及 Qwen3 系列的多个型号是阶梯计价，官方规则是按单次请求的输入 token 总量决定命中哪一档，该请求的全部输入 token 按这一档单价结算，输出 token 不受阶梯规则影响。这条规则本身不会导致报错，但它会让你的账单和预期对不上，然后开始怀疑是不是调错了模型。价格口径这块可以看通义千问 API 怎么收费？。

至于上下文窗口，官方文档里明确标注支持 100 万 token 上下文的包括 qwen-plus（阶梯计价含 256K–1M 档）、qwen3.7-plus、qwen3.6-plus/flash 等新一代型号；而 qwen-max、qwen3-max、qwen3.7-max 在抓到的资料里最高阶梯档是 128K–256K，未见官网标注 1M 档。这里不做进一步推断——某个具体型号的最大上下文到底多长，请以模型广场里该模型详情页写的为准。把长文喂给一个上下文没那么长的型号，报的错也可能不是”超长”这种一眼能懂的措辞。

第四类：区域与额度，报错在调用侧、原因在账户侧

前三类排完还是不通，就该看账户状态了。这一类的特征是代码完全没问题，昨天还能跑，今天突然不行。

区域独立核算。中国内地版与新加坡国际版的免费额度是分别独立核算、互不相通的。也就是说你在内地站还剩额度，不代表国际站端点能用。密钥、端点、额度这三样必须属于同一个区域，任意一个错配都会失败。

免费额度有有效期。官方说明写的是，自 2025-09-08 11:00 起，新用户免费额度的有效期统一调整为 90 天（此前已开通的账号不受影响）。90 天是从开通算起的，不是从第一次调用算起，所以有人开通后放了几个月，等真正要用的时候额度已经过期了。

免费额度按模型分池，不互通。以 qwen-max 为例，官方文档给出的是输入、输出各 100 万 token 的免费额度；其他模型如 qwen-plus 等也各有独立的额度池，模型之间不互相调剂。具体每个模型给多少，以该模型详情页标注的”免费额度”为准。所以”我明明还有额度”这句话要问清楚：还有的是哪个模型的额度。

免费额度不覆盖所有调用方式。官方明确写了，免费额度仅抵扣实时推理调用，不支持 Batch 批量调用、Context Cache 上下文缓存、模型调优、模型部署等场景的费用。这是一个高频困惑点：一个人为了省钱把请求改成批量调用，结果发现免费额度纹丝不动、账户反而开始欠费。省钱手段和免费额度是两条独立的线。

未认证账号额度用完就停。官方说明是，未认证用户在额度用完后无法继续调用，需要完成企业或个人实名认证并完成充值，才能转为按量付费继续用。这类停用不是限速、不会自动恢复，只能去控制台补认证和充值。免费额度的细则可以看通义千问免费额度怎么算？。

至于 Batch 打折、Context Cache 折扣这些优惠规则，官方规则确认是存在的（两者不可叠加），但具体哪些型号支持，需要到对应的模型详情页确认，本文不替官方下结论。

排查顺序建议

把上面四类串成一条固定流程，比看到报错就上网搜错误码要快：

先确认环境变量真的读到了——打印一下，None 就到此为止，先修环境。
再确认 base_url 和密钥属于同一区域——内地密钥配内地端点，国际站密钥配国际站端点，别混。用带 WorkspaceId 的新格式就检查占位符是否已替换。
然后原样复制模型广场里的代号——不要手敲，不要凭已有型号推断新型号是否存在。
最后看账户侧——免费额度是否过期、是否用在了不被覆盖的调用方式上、是否需要实名和充值。

顺序不能反。先怀疑业务代码逻辑是最浪费时间的路径，因为这四类问题中的任何一个，都会在你还没进入业务逻辑之前就把请求打回来。

另外提醒一句关于信息来源的纪律：百炼的价格、免费额度规则、模型代号迭代都比较频繁，本文提到的数字来自官方帮助中心页面在核实当时的内容，但不代表你读到这篇的时候仍然一致。任何要写进生产配置的数字，都该回到官方文档和控制台再核一遍。涉及境外区域端点的使用，还要留意各厂商官方公布的受支持地区与合规要求，以各官网当前的地区政策页为准，本文不提供也不背书任何第三方中转渠道。

这篇的局限

有几处这篇没法给出确定答案，说清楚比含糊过去好：

经典 base_url 与带 WorkspaceId 的新端点之间的权威关系，官方文档没有一句话讲透，本文只能建议以控制台当页显示为准。
逐个型号对齐的完整规格表（每个模型的最大上下文、是否支持 Batch 与缓存），公开资料没有一份完整对齐的版本，只能一个个查模型详情页。
具体错误码到原因的映射表本文没有给。原因是这类映射会随平台版本变动，网上流传的解释很多已经过期，照抄反而会把排查方向带偏。用上面的分类顺序比背错误码更耐用。

小结

通义千问 API 的报错，先按鉴权、模型名、区域与额度这个顺序分类，比追着错误码查含义高效得多。鉴权类里最常见的不是密钥失效，而是环境变量没读到、base_url 从别处迁移过来忘了改。模型名类的坑源于经典命名和 Qwen3 新系列同时在售，唯一可靠的做法是从模型广场原样复制代号。区域与额度类的问题往往表现在调用侧、根因在账户侧，内地站与国际站额度独立、免费额度 90 天有效且不覆盖批量调用与缓存，这几条要单独记住。所有具体数字和端点，最终都以官方文档和控制台当天显示的为准。