knowledge-work-pluginsZoom Meeting SDK Web 错误码全解——从 join 失败到 2026 年 OBF/ZAK 令牌治理【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins本篇基于 Zoom Meeting SDK 插件中的错误码参考文档 error-codes.md系统讲解 Meeting SDK for Web 返回的全部错误码分区、含义与修复方案。读完你将能够按错误码区间快速定位问题类别认证、会议校验、连接、令牌、版本为 Client View 与 Component View 两种 API 风格编写健壮的 join 错误处理逻辑并在 2026 年 OBF/ZAK 令牌强制策略下正确完成外部会议的授权入会。1. 错误码体系总览先按区间定位类别Meeting SDK 的错误码按数值区间划分类别拿到错误码后第一步是判断它属于哪个区间再进入具体修复流程Code RangeCategory0-2General/Success3000-3999Meeting Validation4000-4999Connection Status6000System/Service10000SDK Version13000Simulive理解这套错误码的前提是先分清 Web 端两种集成形态因为错误处理写法在两者间不同维度Client ViewComponent View对象ZoomMtg全局单例ZoomMtgEmbedded.createClient()实例API 风格Callbackssuccess/error 回调Promisesawait/try-catch错误载体err.errorCode数字码error.reason名称error.message描述密码参数passWord大写 Wpassword小写事件监听inMeetingServiceListener()on()/off()这一对照关系与仓库中 web/SKILL.md 的 Client View vs Component View 表格完全一致。错误码文档本身也印证了这一点Component View 捕获到的错误对象使用error.reason WRONG_MEETING_PASSWORD这样的名称匹配而非数字码匹配。2. 通用错误0-2CodeNameDescriptionSolution0SUCCESSFunction invoked successfullyN/A1FAILGeneral function errorCheck parameters and SDK state2MEETING_NOT_INITMeeting not initializedCallinit()beforejoin()2 (MEETING_NOT_INIT)是最典型的生命周期顺序错误。仓库配套文档 common-issues.md 给出了精确的成因与修复join()在init()完成回调之前被调用。错误写法是ZoomMtg.init({...}); ZoomMtg.join({...})连续执行正确写法是把join()放进init()的success回调里等待初始化完成。3. 会议校验错误3000-39993xxx 区间是 join 流程中最高频的错误类别细分为认证、会议本体、注册登录、主持人、平台限制五组。3.1 认证类错误CodeNameDescriptionSolution3704API_KEY_INVALIDSDK Key/Client ID is invalidVerify SDK credentials in Marketplace3705SIGNATURE_EXPIREDJWT signature has expiredGenerate new signature with validexp3708ROLE_ERRORIncorrect role in signatureUse role 0 (participant) or 1 (host)3710API_KEY_DISABLEDSDK Key is deactivatedRe-enable in Marketplace or create new app3712SIGNATURE_INVALIDSignature verification failedCheck SDK secret, verify signature generation3265TOKEN_ERRORToken validation failedCheck ZAK/OBF token format and expiry3623TOKEN_ERROR_ALTToken error (alternate)Same as 32653713NO_PERMISSIONInsufficient permissionsVerify account permissions and scopes这组错误的根源几乎全部落在签名生成与令牌管理上仓库内两份文档提供了纵深佐证signature-playbook.md 列出了签名失效的四种常见模式secret 错误、mn会议号格式错误必须为纯数字串、exp/tokenExp过期、以 role1主持人生成签名却执行 participant 入会或反之。其中 role 不匹配正好对应错误码表中的3708 ROLE_ERROR。common-issues.md 补充了一个版本相关的细节v5.0.0 起签名需要appKey前缀格式为appKey:sdkKey.eyJhbGc...使用旧格式会导致 3712此外算法必须为 HS256。关于 ZAK/OBF 令牌类的3265/3623bot-authentication.md 明确了令牌属性ZAK 是短时效凭证TTL 可配通常 1-2 小时到期时间在 join 时校验若机器人已在会中即使令牌过期也不会被断开。因此 3265 优先排查方向是令牌过期或令牌格式错误而不是令牌与参会人身份不匹配——任何 Zoom 账号的 ZAK 都满足仅认证用户可加入的要求。3.2 会议本体错误CodeNameDescriptionSolution3001ERROR_NOT_EXISTMeeting does not existVerify meeting number3003ERROR_NOT_HOSTNot meeting hostUse hosts ZAK token to start3004WRONG_MEETING_PASSWORDIncorrect passwordVerifypassWord(Client View) orpassword(Component View)3005ANOTHER_MEETING_RUNNINGAlready in another meetingLeave current meeting first3008MEETING_NOT_STARTMeeting hasnt startedWait for host or use join before host3009BE_REMOVEDUser was removed from meetingCannot rejoin; contact host3610MEETING_NOT_EXIST_ALTMeeting does not exist (alt)Same as 3001其中三个码值得结合仓库文档展开3004 WRONG_MEETING_PASSWORD与字段名陷阱。错误码表给出的 Solution 直接指向 Web SDK 最著名的坑Client View 用passWord大写 WComponent View 用password小写。signature-playbook.md 特别强调当会议有密码但字段缺失/写错时join 会以看似认证问题的方式失败。common-issues.md 补充了另外两个高频诱因密码中含空格/编码问题、直接使用了 URL 编码后的密码正确做法是从邀请链接用url.searchParams.get(pwd)提取原始密码。3005 ANOTHER_MEETING_RUNNING的处理。修复方式是先调用ZoomMtg.leaveMeeting({})离开当前会议再 join 新会议。这与仓库 references/multiple-meetings.md 所讨论的多会议/多实例场景直接相关单例ZoomMtg同一时刻只能承载一个会议。3001/3610 ERROR_NOT_EXIST的会议号 vs 会议 ID。错误码文档给出一个关键事实Meeting ID来自 API和 Meeting Number客户端显示是同一个号码问题通常是拼写、会议被删除或把 API 返回的完整会议对象里的其他字段误当成号码。配合 web/SKILL.md 中的Helper Utilities一节可以从用户粘贴的完整邀请链接中正则提取 9-11 位纯数字作为meetingNumber。3.3 注册与登录错误CodeNameDescriptionSolution3000EMAIL_REQUIREDEmail required for webinarProvideuserEmailin join params3099REGISTRATION_REQUIREDMeeting requires registrationGettktoken from registration API3100LOGIN_REQUIREDZoom login requiredProvide ZAK token for authenticated join3624HOST_EMAIL_REQUIREDHost/alt host needed for webinarUse host credentials to start这组错误对应 join 参数中的三个认证字段userEmailwebinar 必需、tk注册令牌、zakZAK 令牌。web/SKILL.md 的ZoomMtg.join()参数表中列出了这些字段tk: stringRegistration token, if required、zak: stringHosts ZAK token, required to start、userEmail: stringRequired for webinars。3100 LOGIN_REQUIRED常见于开启了仅认证用户可加入的会议修复方式是用 OAuth 流程获取 ZAK 后传入 join 参数完整流程见 bot-authentication.mduser:read:zakscopeGET /v2/users/me/token?typezak。3.4 主持人错误CodeNameDescriptionSolution3625HOST_INACTIVEMeeting host is inactiveContact host to activate account3702HOST_NOT_FOUNDHost does not existVerify host account3709HOST_NOT_FOUNDHost not found (alt)Same as 37023711CANT_HOST_CONCURRENTCant host multiple meetingsEnd other meeting first注意3702与3709名称相同HOST_NOT_FOUND但码值不同属于别名关系排查时可按同一问题处理。3003 ERROR_NOT_HOST与3711都指向主持人身份/并发问题以主持人身份启动会议需要主持人账号的 ZAK 令牌且一个主持人账号不能同时主持多个会议。signature-playbook.md 还提到一个关联失败模式Web start 流程中 role 不匹配或缺少主持人要求时常表现为4003 INVALID_PARAMETER主持人启动流通常还需要 ZAK 配合。3.5 平台限制错误CodeNameDescriptionSolution3603NOT_SUPPORT_WEBCLIENTWeb join not allowedAdmin must enable web client3608TSP_NOT_SUPPORTTSP audio not supported on webUse computer audio or phone3611USE_DESKTOP_OR_MOBILEBrowser join disabledUse Zoom desktop/mobile app3620EMAIL_BLOCKEDEmail blocked by adminContact account administrator3621NO_RESPONSE_FROM_WEBServer timeoutRetry request这组错误的特点是根因在管理端策略而非客户端代码3603/3611/3620 都需要联系会议所在账号的管理员调整 Web 客户端开关或邮件域策略客户端代码无论怎么改都无法绕过。3608则是音频模式限制TSP 电话音频在 Web 端不支持改走电脑音频或电话入会即可。3.6 深度解析3712 签名失败的完整排查链3712 是认证类错误中信息量最大的一个。综合错误码文档与仓库内 common-issues.md、signature-playbook.mdSignature is invalid 的完整原因清单如下SDK Secret 与 SDK Key 不匹配来自不同应用或拼写错误签名算法错误必须 HS256服务器与 Zoom 之间的时钟偏移需 NTP 同步signature-playbook.md 将其列为 works locally but not in prod 的典型根因之一签名中缺少或错误的appKey字段v5.0.0 格式要求appKey:sdkKey.eyJhbGc...前缀mn字段非纯数字签名 payload 中会议号必须归一化为数字字符串role 与实际行为不一致生成 role1 却执行 participant join。调试步骤在 Marketplace 中核对 SDK Key/Secret → 复查签名生成代码的 payload 字段sdkKey、mn、role、iat、exp、tokenExp→ 确认服务器时间准确 → 使用官方 auth-endpoint 样例工程交叉验证。注意区分两个易混概念见 bot-authentication.md 的 Common Confusion 一节被弃用的是 REST API 的JWT App Type而 Meeting SDK 用的JWT 签名从未弃用仍为每次 join 的必需凭证。4. 连接状态错误4000-4999CodeNameDescriptionSolution4000RE_CONNECTINGReconnecting to meetingWait for reconnection4001DISCONNECTDisconnected from meetingCheck network, try rejoining4003INVALID_PARAMETERInvalid join parameterCheck all required fields4004MEETING_ENDEDMeeting has endedCannot join ended meeting4005MEETING_CAPACITY_REACHEDMeeting is fullHost needs to increase capacity4006MEETING_LOCKEDMeeting is lockedHost must unlock to allow joins4007REJECT_BARRIERSInformation barriers rejectionContact admin about policies4008PARTICIPANT_EXISTAlready a participantAlready in meeting or leave first4009SERVER_ERRORInternal server errorRetry request4011NOT_ALLOW_CROSS_JOINCross-account join blockedPublish app on Marketplace与 3xxx 区间不同4xxx 更多是入会时的状态性拒绝会议已结束4004、已满员4005、已锁定4006、参会人已存在4008等其中 4004/4005/4006 的解决方都在主持人或管理端。两个值得注意的码4003 INVALID_PARAMETERsignature-playbook.md 指出这是 Web start主持人启动流程的高发错误常见根因是 role 不匹配或缺少主持人要求通常需要 ZAK。排查方向应从参数合法性和角色一致性两个维度并行切入。4011 NOT_ALLOW_CROSS_JOIN跨账号入会被拦截。错误码文档给出的解决路径有三条将应用发布到 Zoom Marketplace、仅入会本账号内的会议、或使用 OBF 令牌授权。bot-authentication.md 补充了一个关键前提开发dev凭据只能入会本账号的会议跨账号场景需要生产production凭据。5. OBF/匿名入会错误2026 年 3 月起与令牌治理5.1 4012 / 4013 错误码与响应结构错误码文档标注自 2026 年 3 月 2 日起匿名加入外部会议被禁止必须提供有效的 OBF 或 ZAK 令牌。CodeNameDescriptionSolution4012NOT_ALLOW_ANONYMOUS_JOINAnonymous join not allowedProvide valid OBF or ZAK token4013USER_LEVEL_TOKEN_NOT_HAVE_HOST_ZAK_OBFOBF/ZAK token invalid or missingVerify token is not expired or malformed两个码的实际错误响应体meetingStatus: 3表示 disconnected/失败态4012 Error Response{ meetingStatus: 3, errorCode: 4012, errorMessage: Anonymous joins are not allowed for this SDK app. Authenticate the Zoom user and provide a ZAK or OBF token. }4012 的解决方案通过 Zoom API 生成 OBF 令牌或为用户获取 ZAK 令牌/users/me/zak将令牌传入 join 参数的obfToken或zak字段。4013 Error Response{ meetingStatus: 3, errorCode: 4013, errorMessage: The OBF or ZAK token is not provided or invalid. Make sure its not expired or malformed. }4013 的解决方案检查令牌是否过期OBF 令牌有有效期验证令牌格式正确过期则重新生成。4012 与 4013 的区分语义4012 是根本没提供令牌匿名 join 被策略拒绝4013 是提供了但无效过期或格式错误。5.2 OBF 与 ZAK 令牌模型选哪个、怎么传bot-authentication.md 给出了两者最关键的行为差异直接影响 join 失败时的重试设计维度ZAK TokenOBF Token需要授权用户在场否是——用户必须在会中用户离场后机器人连接保持令牌持有者离场不断连立即断开会议范围任意会议仅绑定的特定会议 ID归因方式通用认证绑定到具体参会用户实现层面的要点互斥zak与obfToken不能同时传只能二选一OBF 生成GET https://api.zoom.us/v2/users/me/token?typeonbehalfmeeting_id{meeting_id}需要 OAuth scopeuser:read:tokenZAK 对应typezakscopeuser:read:zakOBF 的典型失败机器人在授权用户入会前就发起 join会返回特定错误码MEETING_FAIL_AUTHORIZED_USER_NOT_INMEETINGSDK v6.6.10文档给出的修复是带退避的重试循环例如最多 5 次、每次间隔 3 秒而不是把它当作永久性失败。web/SKILL.md 的 Authorization Requirements (2026 Update) 一节同样确认了这条策略线并展示了两种传参方式机器人场景传obfToken: your-app-privilege-token主持人操作场景传zak: host-zak-token。5.3 OBF 强制时间表DateEnforcement2026 年 2 月 7 日若提供了 OBF则必须有效未过期/格式正确2026 年 3 月 2 日无有效 OBF/ZAK 令牌不得加入外部会议需要提示读者一个仓库内的日期差异bot-authentication.md 的 Timeline 一节将外部会议强制时间点写作 2026 年 2 月 23 日。从两份文档的措辞看2 月节点约束的是提供的 OBF 必须有效3 月 2 日节点约束的是必须提供而 bot-authentication 文档可能记录的是策略分阶段执行中的某个中间节点。以错误码文档的时间表为准排查 4012/4013 即可实际项目中建议在发布前向 Zoom 官方渠道复核当前生效日期。6. 系统、SDK 版本与 Simulive 错误CodeNameDescriptionSolution6603BLOCKED_BY_HOST_ADMINSDK Key blocked by hosts adminContact hosts admin to whitelist10000SDK_VERSION_UNSUPPORTEDSDK version no longer supportedUpgrade to latest SDK version13208UNABLE_JOIN_ENDED_SIMULIVESimulive webinar has endedCannot join ended simulive6603是管理端封禁会议主持人的管理员把你的 SDK Key 加入了屏蔽列表客户端无法自救需联系对方管理员加白。10000是版本强制淘汰机制说明 Zoom 对旧 SDK 版本设有支持窗口web/RUNBOOK.md 也建议在发布更新前每季度重新核对版本强制窗口。13208仅出现在 Simulive同步直播网络研讨会场景会议/网络研讨会结束后不可再加入。7. 错误处理模式Client View 与 Component View 的完整写法7.1 Client View基于回调的数字码分支ZoomMtg.join({ // ... options success: (res) { console.log(Joined successfully); }, error: (err) { console.error(Join failed:, err); switch (err.errorCode) { case 3004: alert(Incorrect meeting password); break; case 3712: console.error(Signature invalid - check SDK secret); break; case 4012: console.error(OBF token required for external meetings); break; default: console.error(Error ${err.errorCode}: ${err.errorMessage}); } } });7.2 Component View基于 Promise 的名称匹配try { await client.join({ // ... options }); } catch (error) { console.error(Join failed:, error); // error.reason contains error code // error.message contains description if (error.reason WRONG_MEETING_PASSWORD) { alert(Incorrect password); } }注意 Component View 的错误对象中reason携带的是错误名称与本文表格第二列的 Name 对应如WRONG_MEETING_PASSWORD即 3004message携带描述文本。因此同一份错误码表可以支撑两种匹配风格Client View 按errorCode数字 switchComponent View 按reason字符串判断。7.3 监听连接状态变化入会成功后的断连/重连不经过 join 回调而是通过连接状态事件两种视图的事件名不同// Client View ZoomMtg.inMeetingServiceListener(onMeetingStatus, (data) { // status: 1connecting, 2connected, 3disconnected, 4reconnecting if (data.status 4) { // 对应 4000 RE_CONNECTING } if (data.status 3) { console.error(Disconnected:, data.errorCode); // 对应 4001 DISCONNECT } }); // Component View client.on(connection-change, (payload) { // payload.state: Connecting, Connected, Reconnecting, Closed if (payload.state Closed) { console.error(Connection closed:, payload.reason); } });两个视图的连接状态枚举映射关系综合错误码文档与 web/SKILL.md 的事件表语义Client ViewonMeetingStatus.data.statusComponent Viewconnection-change.payload.state连接中1 (connecting)Connecting已连接2 (connected)Connected已断开3 (disconnected)Closed重连中4 (reconnecting)Reconnecting实践建议UI 层应在 status 4 / Reconnecting 时展示重连提示而非判定失败在 status 3 / Closed 时读取携带的 errorCode/reason 再决定是提示重试还是引导重新 join。common-issues.md 提醒过一类相关陷阱Component View 的事件名是 kebab-caseconnection-change、user-added、user-removed若误用 Client View 的onMeetingStatus/onUserJoin命名回调将永远不触发。8. 常见错误场景手册这一节继承错误码文档的 Common Error Scenarios并合并仓库佐证材料。8.1 Signature is invalid3712原因SDK Secret 与 SDK Key 不匹配签名算法错误必须 HS256服务器与 Zoom 之间的时钟偏移签名中缺少或错误的appKey字段。调试步骤在 Marketplace 核对 SDK Key 和 Secret检查签名生成代码payload 字段、前缀格式确保服务器时间准确NTP 同步使用官方 auth-endpoint 样例工程web/SKILL.md 的 Authentication Endpoint 一节给出了该样例的本地部署方式做对照测试。8.2 Meeting does not exist3001/3610原因会议号拼写错误会议已被删除Meeting ID 与 Meeting Number 混淆。注意文档明确说明 Meeting ID来自 API与 Meeting Number客户端显示是同一个值因此混淆通常发生在从 API 响应取错字段而非二者真的不同。8.3 Anonymous join not allowed4012原因未经授权加入本账号之外的会议未提供 OBF 或 ZAK 令牌。解决方案机器人场景使用 App Privilege TokenOBF用户场景获取该用户的 ZAK 令牌本账号内的会议无需令牌。补充自 bot-authentication.md选择 OBF 还是 ZAK 还要看你对用户离场后机器人是否保活的需求——需要保活选 ZAK需要强归因且绑定特定会议选 OBF但接受授权用户离场即断连。8.4 Cross-account join blocked4011原因应用未在 Marketplace 发布且试图加入本账号之外的会议。解决方案将应用发布到 Zoom Marketplace或仅加入本账号内的会议或使用 OBF 令牌授权。9. 排查工作流把错误码放进 5 分钟预检流程仓库为 Meeting SDK 提供了两级 runbook通用级 RUNBOOK.md 与 Web 级 web/RUNBOOK.md其Fast Decision Tree与错误码区间的对应关系是join 快速失败 401/签名类错误3704/3705/3712→ 后端签名 claims、时钟偏移、应用凭据不匹配UI 正常但无法入会3001/3004/3008 等→ role/ZAK/密码字段错误或会议数据无效重点核对passWordvspassword连接中断/重连4000/4001/4013→ 先走连接状态监听分支再检查令牌有效期跨账号场景4011/4012→ 检查 Marketplace 发布状态与 OBF/ZAK 配置。runbook 还给出两条可直接执行的探测命令需先设置$MEETING_SDK_BASE_URL# 1) Verify signature endpoint responds with JSON curl -sS -i $MEETING_SDK_BASE_URL/api/signature # 2) Verify app page is reachable and returns HTML curl -sS -i $MEETING_SDK_BASE_URL预期结果是端点返回有效的 JSON/HTML而非通用 404/502 页面——若签名端点本身不可达join 会失败得像认证问题实际是后端问题错误码文档中 3712/3704 的 Solution 都不适用。10. 关联文档索引围绕本错误码文档仓库内以下文件可继续深入web/troubleshooting/common-issues.md高频问题的快速诊断init 顺序、CDN 加载、CORS、React 集成web/SKILL.mdClient View / Component View 完整 API 与 2026 授权要求references/bot-authentication.mdJWT 签名 / ZAK / OBF 三种令牌的行为差异与机器人入会流程references/signature-playbook.md签名生成规则与常见失效模式references/troubleshooting.md跨平台Web/移动/桌面的通用故障排查web/RUNBOOK.md 与 RUNBOOK.md5 分钟预检流程与快速决策树。适用前提说明本文内容基于当前仓库中 zoom-plugin 的 Meeting SDK Web 文档整理其中 2026 年 OBF/ZAK 强制策略的时间节点以仓库文档记载为准错误码数值与名称可能随 SDK 版本演进生产环境排障时建议对照所用 SDK 版本核对。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考