API 401 / 403 / 429

401 是没有带密钥或密钥不对，403 是密钥的权限不够，429 是请求太频繁。响应 JSON 里的 code 比状态码更具体。

症状

• 401，code 为 NO_API_KEY 或 BAD_API_KEY。
• 403，code 为 SCOPE_FORBIDDEN。
• 429，code 为 RATE_LIMIT，带 retryAfter。

检查顺序

1. 读响应体的 code 和 message，不要只看状态码。
2. NO_API_KEY：服务端事件和日志导入要求在 Authorization: Bearer 或 X-Api-Key 里带密钥。头没写、写成查询参数、或 Bearer 后面为空，都是这一条。
3. BAD_API_KEY：密钥不存在、已撤销、已过期，或没有绑定项目。密钥只在创建时显示一次完整值，前缀是 wck_。
4. SCOPE_FORBIDDEN：密钥有效，但缺少该接口需要的权限范围：行为事件要 track:write，机器人访问记录要 events:write，日志导入要 logs:write。
5. 429：等 retryAfter 秒再试。服务端行为事件是每把密钥每分钟 600 次请求，单次最多 1000 条事件。

原因

401 发生在服务端还没认出调用者的时候；403 发生在调用者已认出、但这把密钥不能调用该接口的时候；429 发生在频率窗口已满的时候。浏览器采集不走这套限流，超出时仍返回 202 并丢弃，见 SDK 网络与重试。

修复

• 在 控制台配置设置API 密钥 新建一把带正确范围的密钥。完整密钥只放进服务端环境变量，不要写进前端代码。
• 范围不够时修改密钥范围或换一把，而不是重试。重试不会把 403 变成 200。
• 429 时按 retryAfter 退避，并把多条事件放进同一次请求的 events 数组，而不是一条事件发一次请求。
• 密钥与范围见 认证与密钥，错误体结构见 错误码，限流见 速率限制。

验证

不带 Authorization 调用一次服务端事件接口，应得到 401 / NO_API_KEY。带一把有 track:write 的密钥并开启调试模式，应返回校验结果且不入库。

仍然失败？

按 联系支持 提交状态码、code、message、请求路径和方法、密钥前 8 位与密钥名称。不要粘贴完整密钥，也不要贴 Authorization 头的原文。

SDK 网络与重试

采集端返回 202 时，带队列的 SDK 会把这一批从队列里删掉，即使服务端随后决定不入库。

症状

• 断网几分钟后，小程序或 React Native 的事件补上来了，网站刷新前的那次浏览没有补上。
• 调试日志里出现 switch endpoint → …，或错误回调收到 send_failed：HTTP <状态码>, batch of <条数> dropped。
• Android 进程一杀，内存里还没发出去的事件没了。

检查顺序

1. 看是哪一种 SDK。w.js 优先 sendBeacon，不行再用 fetch（keepalive，不带凭据）。它没有本地队列，页面关掉时没送出的那次就没了。第一次页面浏览改用能读响应的 fetch，用来拿站点配置。
2. 小程序、HarmonyOS、React Native、uni-app 共用 JavaScript 核心：本地队列默认最多 10000 条、保留 7 天、大约 1 MB。429、5xx 和网络错误（状态 0）从 1 秒起指数退避，上限 300 秒。配置了多个收数地址时，连续失败 10 次就换下一个。
3. 其它 4xx（不是 429）：核心认为这一批不会自己变好，从队列删除并记 send_failed。密钥、路径、JSON 结构错误属于这一类。
4. Android 与 iOS 的 0.1.0 只有内存队列，失败不退避，等下次发送再试。进程结束，队列消失。它们也不读远程配置。
5. 收数地址只填域名，SDK 自己拼 /api/v1/pulse。多写了路径会打到错误 URL，得到 404 一类的 4xx，队列会丢掉该批。
6. 采集端对「域名不对、额度用尽、排除规则」仍然返回 202。SDK 看到 2xx 就确认该批，不会重试。报表没有数据时不要在重试日志里找，去看 统计无数据。

原因

网站脚本要小，所以不在浏览器里堆队列。带存储的 SDK 把可恢复的失败（限流、服务器错误、断网）留在本地，把不可恢复的 4xx 丢掉，避免坏数据永远堵住队列。202 在这条链上被当成成功，因为采集端用它表示「我处理完了」，包括「我决定不入库」。

修复

• 网站丢在关闭瞬间的浏览，无法靠重试找回来。确认页面还在时请求已经发出。拦截与 CSP 见 CSP、拦截与网络限制。
• 收数地址与控制台「SDK 代码」页一致，不要自行加 /api/v1/pulse。
• 看到非 429 的 4xx：看响应体，修密钥、路径或字段，再发新事件。旧的那一批已经被确认删除。
• 429 时让队列自己退避，不要同时再开一条不用队列的直发把同一批打第二次。
• 能力对照见 SDK 总览与支持矩阵，浏览器采集协议见 浏览器采集。

验证

小程序或 React Native 上断网发送一条事件，再恢复网络：队列应在退避后发出，实时里出现。把收数地址改成一个返回 404 的路径：该批应被丢弃，而不是无限重试。网站脚本在网络面板里应看到 sendBeacon 或 fetch，没有第二次自动重放。

仍然失败？

按 联系支持 提交 SDK 包名与版本、收数地址的主机名（不要带密钥）、失败时的 HTTP 状态、是否配置了多个地址、队列里大约还有多少条。不要粘贴完整的 API 密钥。

客服气泡不显示

客服和统计共用 w.js。第一条页面浏览的响应告诉脚本要加载客服之后，气泡才会出现。

症状

• 页面上没有气泡，网络面板里也没有 w-chat.js。
• w-chat.js 加载了，气泡仍不出现，尤其是手机。
• 气泡在，访客一发消息就变成留言表单。
• 聊天窗顶部写来源域名不在允许列表。

检查顺序

1. 控制台客服聊天设置外观与品牌 里「开启在线客服」已保存。只有所有者和管理员能改这项。
2. 页面已刷新。已经打开的页面不会自己去拉 w-chat.js。脚本默认等第一条页面浏览的响应：响应里带上客服标志才懒加载同目录的 w-chat.js。
3. 脚本标签没有 data-chat="false"。data-chat="true" 会跳过「等第一条浏览响应」这一步，但开关仍是关的时，气泡还是不出现。
4. 统计本身在上报。没有页面浏览响应，脚本不知道要加载客服。先按 统计无数据 确认采集。
5. 当前域名在允许的域名里。客服沿用统计的这份列表，见 项目与数据源设置。
6. 手机宽度小于 640 像素，或浏览器被认成移动端时，若打开了「移动端隐藏气泡」，气泡会藏起来，脚本仍可能已经加载。
7. 本月会话额度（按站点所有者名下全部项目合计）。达到上限且没有打开超额计费时，新会话被拒绝，访客侧变成留言，气泡本身还在。见 计费与配额。
8. 页面的 CSP 是否挡住了 w-chat.js、客服网关和聊天窗里的页面。见 CSP、拦截与网络限制。

原因

w.js 不在 HTML 里再写一段客服脚本。它用第一条页面浏览的 JSON 配置决定要不要拉 w-chat.js。开关、域名、移动端隐藏和额度作用在这条链的不同点上：前三个决定气泡出不出现，额度决定新会话能不能建立。

修复

按 安装与启用 打开开关并刷新。单页不想要气泡时用 data-chat="false"，不要关全站开关。独立聊天页 https://app.tapcub.com/c/站点标识 不依赖网站嵌码，可用来区分「网站没加载脚本」和「客服服务本身不可用」。

更多客服症状（收不到消息、通知、翻译、离线）见 客服常见问题。

验证

刷新已登记域名上的页面。网络面板出现 w-chat.js，角落出现气泡。发一条测试消息，控制台客服客服工作台 的「待接入」里能看到。坐席在线时气泡上有在线标记。

仍然失败？

按 联系支持 提交：开关是否已保存、网络面板有没有 w.js 和 w-chat.js、脚本上的 data-chat、是否手机宽度、聊天窗是否出现域名或额度提示。不要粘贴完整的 API 密钥。

AI 助手问题

助手入口是 控制台智能运营AI 助手。它先用规则理解问题，只有规则把握不够时才调用平台模型。

症状

• 问题被原样退回，提示换个说法，或追问漏斗步骤。
• 昨天还能回答「近 7 天访客」，今天只给出很窄的规则结果，不再润色。
• 助手说出的事件名在事件列表里不存在。
• 通过 MCP 调用 ask 返回 401 或 429。

检查顺序

1. 问题不是空的，也不超过 500 字。页面上空问题或超长问题直接 400，code 为 VALIDATION；MCP 的 ask 则把超出部分截掉再问。
2. 规则能否对上指标、事件名和时间。规则只使用这个项目里已经出现的事件名。问一个从未上报的事件，会落成澄清，而不是编一个数。
3. 平台是否启用了模型并配置了密钥。没开或没密钥时，助手停在规则路径：把握高的问题仍有数字，把握低的问题只有澄清，没有模型润色。
4. 该项目当日模型调用是否已到上限。默认上限是每个项目、按项目时区的自然日 2000 次（运营可改）。超限后这一次不再调用模型，退回规则结果。计数失败时请求仍走规则，页面不会报错。
5. 结论里的数字应来自刚才执行的查询。模型只被允许改写规则已经算出的句子，不允许增加结果里没有的数。若和报表不一致，先对查询的时间范围和口径，见 日期与时区 与 统计口径。
6. MCP 端点是 /api/v1/mcp，走同一套登录或 API 密钥。401 / 403 / 429 按 API 401 / 403 / 429 处理，不是助手没听懂。

原因

两条路径是故意分开的。规则路径不依赖外部模型，所以模型宕机、没配密钥或当日额度用尽时，能回答的问题还有数。模型路径只在规则信心低于 0.9、没有查出查询、或对话里已有历史时才尝试，并且先扣当日额度。查询执行失败时，接口仍返回，说明写在澄清字段里，而不是抛一条未处理的 500 给页面。

修复

• 把问题说成报表语言：时间范围、指标、可选的拆分。例如「近 7 天访客数，按渠道」。漏斗需要至少两步。
• 事件名与 事件与属性 里已经入库的名字一致，不要用口头别名。
• 模型没开时，用规则能回答的问法，或请运营打开平台模型。这不是项目套餐页面上的一个开关。
• 当日额度用尽就等到项目时区的下一天，或让运营提高该上限。助手功能说明见 AI 洞察助手。

验证

问「近 7 天访客数」。规则应返回一个数，时间范围是项目时区的近 7 天。再问一个不存在的事件名，应得到澄清而不是一个新数字。模型开启时，同一问法的标题可以比规则稿更短，数字仍与查询结果一致。

仍然失败？

按 联系支持 提交问题原文、助手返回的澄清或标题、大约的时间、走的是页面还是 MCP。不要粘贴完整的 API 密钥，也不要贴模型供应商的密钥。