先看失败发生在哪一步
控件显示错误时，在浏览器网络面板查看 /v1/challenge；控件已通过但表单被拒绝时，看你自己后端调用 /v1/siteverify 的响应。不要把 secret、完整 token 或个人信息贴入公开日志。
没有拿到题目
| 错误 | 检查方法 |
|---|---|
| missing_sitekey · 400 | 容器是否填写 data-sitekey，是否仍是 YOUR_SITEKEY。 |
| invalid_sitekey · 404 | key 是否完整，站点是否启用、是否已删除。 |
| origin_not_allowed · 403 | 允许域名是否包含浏览器页面的实际 hostname；www、预览子域和本地 IP 要分别检查。 |
| rate_limited · 429 | 是否反复挂载或循环请求发题；稍后再试，共享出口也可能触发限制。 |
| not_configured · 503 | 服务端未配置站点存储，联系服务维护者。 |
控件无法显示或计算
确认 v1.js、altcha.min.js 和样式文件能成功加载，HTTPS 未被浏览器拦截。若网站配置了 CSP，检查控制台的具体拒绝项，再为脚本、Worker、样式和 challenge 请求配置适当来源；不要直接关闭整个 CSP。React 动态插入的容器需要再次调用 mount。
后端返回 success:false
| error-codes | 检查方法 |
|---|---|
| bad-request | 验证接口只接受 JSON；请求需包含字符串 secret 和 response。 |
| missing-input-secret / invalid-input-secret | 服务端是否加载正确 secret；轮换后是否还使用旧值；站点是否已停用。 |
| missing-input-response | 控件是否放在 form 内，隐藏字段名是否仍是 cap-response，提交格式是否正确。 |
| invalid-input-response | token 是否完整，secret 与 sitekey 是否属于同一站点。不要拼接或修改 token。 |
| timeout-or-duplicate | token 已过期或被消费，重新验证。避免同一表单重复提交。 |
| internal-error / service-unavailable | 验证依赖暂时不可用。停止业务处理，稍后重新验证，不要自动当作成功。 |
如何理解统计
发题数不是访客数，成功校验数也不是提交人数。一人可以多次发题，拿到题目也可能离开页面；因此不能把“成功校验 ÷ 发题”当作精确通过率。控制台显示最近 30 个 UTC 日期的事件与失败原因，异步记录为尽力而为。
校验失败只有在 secret 能识别出站点后才归属到该站点；缺少或错误的 secret、无法解析的请求不会计入某个站点。发题阶段的域名拒绝和限流也不计入校验失败。
完整 IP 仅在发题事件中记录，7 天后不再用于展示并进入清理范围；校验请求来自接入方后端，不记录成访客 IP。事件超过 30 天进入删除范围。清理按批次执行，物理删除时间还取决于维护任务是否正常运行。