错误码与排查

请求体不是合法 JSON（400），或缺少必填字段、字段类型或格式不符（422，例如 nonce 太短）。响应里的 field 会指出是哪个字段。

怎么处理：按 field 修正请求。这是代码问题，原样重试不会成功。

请求没有使用 Content-Type: application/json，例如沿用了 reCAPTCHA / hCaptcha 的表单编码请求。

怎么处理：改用 JSON 请求体，并设置 Content-Type: application/json。

请求体里带了 secret 字段，这是 reCAPTCHA / hCaptcha 的写法。

怎么处理：删掉请求体里的 secret，把 Secret key 放进 Authorization: Bearer 请求头。

请求体超过了大小上限（大多数接口为 4 KB），在读取请求时就被拒绝。

怎么处理：检查是否带了多余字段或大段数据；正常请求远小于这个上限。

JSON 请求体超过了大小上限。

怎么处理：同 body-too-large：去掉多余字段，正常请求远小于这个上限。

缺少 Secret key，或 Secret key 无效。

怎么处理：在 Authorization: Bearer 请求头里使用控制台的 Secret key（mc_sec_…）。更换密钥后旧密钥立即失效；不要误用 Site key。

页面所在域名或 intent 的 hostname 不在站点的允许域名中。

怎么处理：在站点设置里加入完整域名，子域名要单独添加；本地开发请加入 localhost。

Site key 不存在，或站点已暂停、已删除。

怎么处理：核对组件的 data-sitekey，并在控制台确认站点处于启用状态。

这个 nonce 之前用不同的 action、hostname、session 或豁免创建过许可。

怎么处理：每次新的业务操作都生成新 nonce；只有重试同一次创建时才复用 nonce，并且字段必须完全相同。

用同一个 nonce 重试创建时，原许可已经过期（5 分钟）或已被兑换。

怎么处理：生成新的 nonce，创建新的许可。

许可不存在、已过期或已用完，或者 token 与这次兑换的 intent_id、action、hostname、站点对不上。

怎么处理：让访客重新验证：服务端创建新的 intent，重新渲染组件。不要重试同一个请求。

token 为空、格式错误、签名无效，或已超过有效期（约 2 分钟）。

怎么处理：让访客重新验证（新的 intent + 重新渲染组件）。

这个 token 已经被兑换过。可能是重复提交，也可能是 10 分钟后又用同一幂等键重试。

怎么处理：按验证失败处理，让访客重新验证；检查是否有重复提交。

同一个幂等键曾用于不同的 token、intent、action 或 hostname。

怎么处理：每次业务提交使用独立的幂等键；重试时所有参数必须和第一次完全相同。

本月免费额度已用完，且充值余额不足。token 没有被消耗。

怎么处理：在控制台充值后，用同一个请求重试（token 仍需在有效期内）。

挑战在规定时间内没有完成。

怎么处理：组件会显示「重试验证」，通常无需处理；许可也过期时由服务端创建新的 intent。

工作量证明的结果不正确。

怎么处理：组件会自动处理；持续出现时请把请求编号发给我们。

挑战进行中，访客的网络发生了变化。

怎么处理：让访客在当前网络下重新验证。

回传的业务结果不合法，例如 decision_id 不属于这个站点、时间超出范围或字段格式不符。

怎么处理：核对 decision_id（来自 /siteverify 的响应）和各字段格式。

同一个 event_id 已经提交过不同的内容。

怎么处理：新的事件使用新的 event_id；要修正之前的结果，用 supersedes_event_id 指向它。

挑战豁免无效、已过期、已撤销或次数已用完。

怎么处理：不带 trusted_grant_id，创建普通 intent。

同一个 request_id 提交了不同的豁免内容。

怎么处理：重试时使用完全相同的请求；新的豁免使用新的 request_id。

请求过于频繁。

怎么处理：按 Retry-After 等待后重试同一个请求，不要循环重试。

请求体在规定时间内没有上传完。

怎么处理：检查网络后重试同一个请求。

验证服务或它依赖的组件暂时不可用。

怎么处理：用相同的参数和幂等键重试。在得到明确结果前，不要执行业务。

资源不存在，或不属于当前账号。

怎么处理：核对站点 ID、intent ID 或订单号。