Skip to content

错误处理与重试 ​

所有 CaptchaLa SDK 在验证失败时都会给出错误码;从 SDK 1.1.0(Web SDK 2.0.0)起, 还会告诉你该错误能否重试。重试选项都是可选的:一个都不设置时,SDK 的行为与之前完全一致(retry: 'legacy')。

错误分类 ​

按分类(class)处理。所有 SDK 对错误码给出相同的分类和相同的 retryable 值;原生 SDK 中该字段名为 errorClass(Electron 中为 class)。

分类常见错误码可重试建议处理
configapp_not_found、app_disabled、invalid_app_key、domain_not_allowed、pkg_not_allowed、浏览器加密能力不可用否配置问题,不要重试。记录日志并显示通用的“验证暂不可用”提示;在控制台修正 App Key、域名或包名列表。
blockedip_blocked否不要重试,提供其他继续方式(联系客服、其他验证方式)。
subscriptionsubscription_required、subscription_expired、subscription_inactive否到控制台检查套餐。
rate_limitip_rate_limit_exceeded、app_rate_limit_exceeded、too_many_failures、qps_exceeded、rpm_exceeded、daily_limit_exceeded是,需等待 retryAfter至少等待 retryAfter 秒再试,不要循环重试。
server_tokenserver_token_invalid、server_token_exhausted、server_token_required是,需新 token提供 serverTokenProvider(或 onServerTokenExpired),SDK 会获取新 token 并重试;没有的话,获取新 token 后重新开始。
server_token(绑定)server_token_binding_mismatch、server_token_app_mismatch否新 token 的绑定相同。请签发时不带 bind_ip(见 bind_ip),或为正确的应用签发。
businessverify_failed、wrong_answer、challenge_expired、max_attempts_reached是用户答错或超时,组件会自动换题。除非你用 maxBusinessRefreshes 设了上限,否则无需处理。
network无响应、超时、5xx、未知错误码是临时问题。让 SDK 自动重试(retry: 'auto'),或提供“重试”按钮。
clock_skewclock_skew_too_large是SDK 会自动校正一次设备时间。
expiredpass_token_expired是Web 2.0 验证条(animation: 'trace'):pass token 在表单使用前已过期,验证条提示用户重新验证,getValidate() 重新为空。

未知错误码一律按 network 处理,因此服务端新增的错误码不会让旧版 SDK 变成永久失败。

错误详情 ​

Web。 onError 会收到第二个参数,getLastError() 返回同一个对象(React / Vue 封装只传第一个参数):

ts
interface CaptchalaErrorDetail {
  code: string;          // error code; 'network' when the request got no answer
  class: 'config' | 'rate_limit' | 'blocked' | 'subscription'
       | 'server_token' | 'business' | 'network' | 'clock_skew';
  retryable: boolean;    // the same request can succeed later
  retryAfter?: number;   // seconds to wait (rate limits), when the server said so
  reason?: string;       // 'expired' | 'used' | 'unknown' for server-token rejections
  attempt: number;       // attempts made in this verification (1 = first)
  willRetry: boolean;    // the SDK will retry on its own
}
js
Captchala.init({ appKey: 'YOUR_APP_KEY', retry: 'auto' })
  .onError((message, detail) => {
    if (detail.willRetry) return;                 // the SDK is still trying
    if (!detail.retryable) showSupportHint();     // config, blocked, binding …
    else if (detail.retryAfter) showWaitHint(detail.retryAfter);
  });

原生 SDK。 传给 onError / onFail 的错误对象带有同样的字段:code、message、errorClass(取值与 class 相同)、retryable、retryAfter(秒,或无)、reason、attempt 和 willRetry。getLastError() 返回最近一次的错误对象,没有时返回 null;verify() 开始时和验证通过时会清空。原生端的 attempt 统计本次验证发出的 ticket 请求:第一次为 1,SDK 每自动发起一次新请求(限流后重试、用刷新后的 server token 重试)加 1。

SDK错误字段最近一次错误
AndroidCaptchalaError.errorClass、.retryable、.retryAfter、.reason、.attempt、.willRetryCaptchalaClient.getLastError()
iOS / macOSCaptchalaError.errorClass、.retryable、.retryAfter(Objective-C 可用 retryAfterSeconds,无值时为 -1)、.reason、.attempt、.willRetryclient.getLastError()
HarmonyOSCaptchalaError.errorClass、.retryable、.retryAfter、.reason、.attempt、.willRetryclient.getLastError()
Electronverify() reject 的错误和 onFail 的参数:err.code、err.class、err.retryable、err.retryAfter、err.reason、err.attempt、err.willRetry、err.errorLangKeyclient.getLastError()
FlutterCaptchalaError.errorClass、.retryable、.retryAfter、.reason、.attempt、.willRetryawait client.getLastError()
kotlin
override fun onError(error: CaptchalaError) {
    if (error.willRetry) return                                 // the SDK is still trying
    when (error.errorClass) {
        "rate_limit" -> showWaitHint(error.retryAfter)
        "config", "blocked", "subscription" -> showSupportHint(error.errorLangKey)
        else -> if (error.retryable) showRetryButton()
    }
}

重试选项 ​

选项取值默认值说明
retrylegacy / auto / neverlegacylegacy:与旧版 SDK 行为一致。auto:临时错误按退避自动重试(指数退避,最长 30 秒,±20% 抖动);retryAfter 不超过 60 秒的限流在等待结束后重试一次。never:不自动重试,立即上报错误。
retryInterval毫秒Web 1500,原生 1000每次尝试之间的基础间隔。
retryMax数字3Web:放弃前的网络尝试次数。原生:连接尝试次数(同 retryCount)。
retryBackofffixed / exponentialfixed;retry: 'auto' 时为 exponential间隔如何增长。
offlineFallback布尔Web true;原生 = enableOfflineMode(false)见离线兜底。
refreshExpiredmanual / auto / never有 token provider 时 manual,否则 never见 Server token。
serverTokenProvider函数—从你的后端返回新的 server token。与 onServerTokenExpired 约定相同,两者都设置时以它为准;最多等待 10 秒。
maxBusinessRefreshes数字不限仅 Web。一次验证中答错达到该次数后不再换题,onError 以 business 分类触发。
showRetry布尔legacy 下为 false,否则 true仅 Web。临时错误时在错误卡片上显示“重试”按钮。

各平台的写法:

平台设置方式
WebCaptchala.init({ retry, retryInterval, retryMax, retryBackoff, offlineFallback, refreshExpired, serverTokenProvider, maxBusinessRefreshes, showRetry })
React / Vue封装不传入这些选项;请直接使用 Web SDK(见 React、Vue)
AndroidCaptchalaConfig.Builder().retry("auto").retryInterval(…).retryMax(…).retryBackoff(…).offlineFallback(…).refreshExpired(…).serverTokenProvider { … }
iOS / macOSCaptchalaConfigBuilder().retry("auto").retryInterval(…).retryMax(…).retryBackoff(…).offlineFallback(…).refreshExpired(…).serverTokenProvider { … }
HarmonyOSsetRetry('auto')、setRetryInterval、setRetryMax、setRetryBackoff、setOfflineFallback、setRefreshExpired、setServerTokenProvider
Electronnew CaptchalaClient({ retry, retryInterval, retryMax, retryBackoff, offlineFallback, refreshExpired, serverTokenProvider })
FlutterCaptchalaConfig(retry:, retryInterval:, retryMax:, retryBackoff:, offlineFallback:, refreshExpired:);setCallbacks(serverTokenProvider: …)

Server token ​

每次开始挑战都会消耗一次 server token,包括组件自己发起的开始(刷新图标、关闭后重新打开、 答错后换题、reset() 后 verify())。因此以 max_uses=1 签发的 token 在第二次开始时就会失败, 除非你给 SDK 提供获取新 token 的方式。

  • serverTokenProvider(或 onServerTokenExpired):服务端拒绝 token 时调用。从你的后端返回新 token, SDK 用它重试;返回 null 则放弃。
  • refreshExpired:
    • manual(有 provider 时的默认值):被拒后询问 provider(Web:每次 verify() 一次;原生:每次验证最多 3 次)。
    • auto:在会复用上一次已消耗 token 的重新开始之前也询问 provider;Web 上若 provider 返回 { token, expiresIn },还会在即将过期前刷新。
    • never:从不询问。
  • setServerToken(token)(React / Vue 封装以外的所有 SDK): 直接替换 token,例如在 onError 中获取新 token 后,再调用 verify()。新 token 用于下一次 ticket 请求, 并替换 provider 之前返回的 token。可以在 verify() 之前或两次 verify() 之间、从任意线程调用; 它本身不会发起验证。空 token 会被忽略。
  • 在 retry: 'auto' 或 'never' 下,绑定不一致和应用不一致不会刷新,因为新 token 的绑定相同。

服务端如果你的页面可能多次启动组件,请保留默认的 max_uses,见 server token 的使用方式。

限流 ​

  • 限流回应(HTTP 429 或限流错误码)以 rate_limit 类错误上报,带 retryable 和 retryAfter;SDK 默认不重试。
  • retry: 'auto' 时,若等待时间不超过 60 秒,SDK 会等待 retryAfter 后重试一次;Web 的“重试”按钮会倒计时。 更长的等待直接上报。
  • 不要在 retryAfter 结束前重试。

离线兜底 ​

CaptchaLa API 真正故障时,SDK 可以通过兜底路径完成验证,结果会被标记为离线(offline / isOffline; 所有服务都不可达时还有 clientOnly / isClientOnly)。

默认值关闭时
WebofflineFallback: true(原有行为)达到 retryMax 次后错误交给 onError(showRetry 时显示“重试”按钮),不会离线通过
原生(Android、iOS、HarmonyOS、桌面端、Electron、Flutter)offlineFallback = enableOfflineMode,默认 false失败即关闭(fail-closed):故障以 onError 结束,绝不会离线通过或给出 client-only 结果

服务端的明确回答(答错、限流、配置或 server token 错误)从不走离线路径。是否接受离线结果由你的后端决定, 见 Token 类型。

服务端返回的字段 ​

CaptchaLa API 的错误回应保持原有错误码和结构,并新增 SDK 会透传的可选字段:

字段出现于含义
retryableserver_token_*、限流、too_many_failures同样的请求之后能否成功
retry_after限流(HTTP 429、签发限流)、too_many_failures下次请求前需等待的秒数
reasonserver_token_invalid(expired / used / unknown)、server_token_exhausted(used)token 被拒的原因

旧版 SDK 会忽略这些字段。

MIT-licensed examples · CaptchaLa is operated independently