客户端错误

在某些情况下，Turnstile 可能会遇到问题，并调用 error-callback 回调函数。

这些问题可能包括网络连接问题、浏览器兼容性问题、配置错误以及质询失败。

发生错误时，实施妥善的错误处理可确保您的访问者收到有用的反馈，并且您的应用程序能够从临时问题中恢复。

有关解决特定错误情况的故障排除指导，请参阅错误代码。

错误处理

用于显式渲染小组件的 error-callback 选项和用于隐式渲染的 data-error-callback 属性，提供了一个 JavaScript 回调来处理可能发生的错误。

此回调机制让您能够完全控制如何向访问者展示错误，并允许您实施适合应用程序需求的自定义恢复策略。

turnstile.render('#my-widget', {
  sitekey: 'your-sitekey',
  'error-callback': function(errorCode) {
    console.error('发生 Turnstile 错误：', errorCode);
    handleTurnstileError(errorCode);
    return true; // 指示我们已处理该错误
  }
});

HTMLhtml

<div class="cf-turnstile" 
     data-sitekey="your-sitekey" 
     data-error-callback="onTurnstileError"></div>

指定错误回调是可选的，但建议在生产环境应用程序中进行配置。如果未设置错误回调，Turnstile 将在发生错误时抛出 JavaScript 异常，这可能会破坏页面的功能并导致不良的用户体验。通过提供错误回调，您可以捕获这些异常并进行处理。

如果错误回调返回非虚值 (non-falsy result)，Turnstile 将认为该错误回调已对错误进行了相应处理，并且不会执行任何额外的错误记录。如果错误回调返回虚值（包括 undefined），Turnstile 将在 JavaScript 控制台中记录一条包含错误代码的警告，这在开发期间进行调试非常有用。

错误回调函数将接收错误代码作为其第一个参数。此错误代码采用结构化格式，其中前三位数字表示错误系列（例如配置问题、网络问题或质询失败），其余数字指定该系列中的确切错误。

function handleTurnstileError(errorCode) {
  const errorFamily = Math.floor(errorCode / 1000);
  
  switch(errorFamily) {
    case 100:
      showMessage('请刷新页面并重试。');
      break;
    case 110:
      showMessage('配置错误。请联系支持人员。');
      break;
    case 300:
    case 600:
      showMessage('安全检查失败。请尝试刷新或使用其他浏览器。');
      break;
    default:
      showMessage('发生非预期错误。请重试。');
  }
}

重试

默认情况下，Turnstile 会在遇到问题时自动重试，这有助于在无需用户干预的情况下处理瞬时网络问题或临时服务中断。

此自动重试机制对于可能经历断断续续连接的移动端访问者，或在稳定性偶发问题的网络下的访问者非常有用。

当观察到由于重试导致的后续失败时，对于同一个底层问题，错误回调可能会被调用多次。您的错误处理代码应考虑到这一可能性，以避免显示重复的错误消息或重复执行相同的恢复操作。

let retryCount = 0;

turnstile.render('#my-widget', {
  sitekey: 'your-sitekey',
  'error-callback': function(errorCode) {
    retryCount++;
    
    if (retryCount <= 2) {
      console.log(`Turnstile 重试尝试第 ${retryCount} 次`);
      return false; // 让 Turnstile 处理重试
    } else {
      showPersistentErrorMessage(errorCode);
      return true; // 我们将从此开始处理
    }
  }
});

您可以通过将 retry 值设置为 never（而不是默认的 auto）来调整重试行为。这将使 Turnstile 不会自动重试，从而让您控制何时以及如何进行恢复尝试。如果验证访问者时出现任何问题或错误，小组件将不会重试，并将保持在相应的失败状态，直到您采取手动操作。

turnstile.render('#my-widget', {
  sitekey: 'your-sitekey',
  retry: 'never',
  'error-callback': function(errorCode) {
    // 您控制所有的重试逻辑
    setTimeout(() => {
      turnstile.reset('#my-widget');
    }, 3000);
  }
});

您可以在相应的 error-callback 中调用 turnstile.reset() 来手动触发重试。当您想要实施自定义重试逻辑（例如指数退避、在重试前向用户确认，或者根据遇到的具体错误采取不同的重试策略）时，此方法很有用。

可以通过 retry-interval 选项配置 Turnstile 的重试间隔，允许您针对访问者的典型网络条件优化重试时机。对于连接较慢或不太可靠的访问者，较长的间隔可能更为合适，而在通常稳定的连接环境下，较短的间隔效果较好。

turnstile.render('#my-widget', {
  sitekey: 'your-sitekey',
  retry: 'auto',
  'retry-interval': 8000, // 重试之间等待 8 秒
  'error-callback': handleError
});

交互性

如果访问者未在合理的时间范围内参与交互式质询，则会触发超时回调函数。此超时机制可防止质询无限期地保持在挂起状态，并确保在需要采取行动时访问者能收到反馈。

例如，在将 Turnstile 小组件实施在可能需要几分钟才能完成的表单中的场景下，如果小组件中的交互式质询在很长一段时间内未被处理，它就会变得过时。访问者可能会专注于填写表单字段而忽略了 Turnstile 质询，导致他们尝试使用已过期或无效的令牌提交表单。

在这种情况下，小组件的 timeout-callback 将被激活，使小组件能够根据需要自行重置并提供适当的引导。此回调允许您实施对用户友好的超时处理，例如突出显示 Turnstile 小组件、显示通知或自动刷新质询。

turnstile.render('#my-widget', {
  sitekey: 'your-sitekey',
  callback: function(token) {
    console.log('质询成功完成');
  },
  'timeout-callback': function() {
    console.log('质询超时 - 需要用户操作');
    document.getElementById('challenge-notice').textContent = 
      '请完成上方的安全检查以继续。';
    
    // （可选）突出显示 widget
    document.getElementById('my-widget').style.border = '2px solid orange';
  },
  'expired-callback': function() {
    console.log('令牌已过期 - 质询需要刷新');
    document.getElementById('challenge-notice').textContent = 
      '安全检查已过期。请重试。';
  }
});