错误处理与重试
所有 CaptchaLa SDK 在验证失败时都会给出错误码;从 SDK 1.1.0(Web SDK 2.0.0)起, 还会告诉你该错误能否重试。重试选项都是可选的:一个都不设置时,SDK 的行为与之前完全一致(retry: 'legacy')。
错误分类
按分类(class)处理。所有 SDK 对错误码给出相同的分类和相同的 retryable 值;原生 SDK 中该字段名为 errorClass(Electron 中为 class)。
| 分类 | 常见错误码 | 可重试 | 建议处理 |
|---|---|---|---|
config | app_not_found、app_disabled、invalid_app_key、domain_not_allowed、pkg_not_allowed、浏览器加密能力不可用 | 否 | 配置问题,不要重试。记录日志并显示通用的“验证暂不可用”提示;在控制台修正 App Key、域名或包名列表。 |
blocked | ip_blocked | 否 | 不要重试,提供其他继续方式(联系客服、其他验证方式)。 |
subscription | subscription_required、subscription_expired、subscription_inactive | 否 | 到控制台检查套餐。 |
rate_limit | ip_rate_limit_exceeded、app_rate_limit_exceeded、too_many_failures、qps_exceeded、rpm_exceeded、daily_limit_exceeded | 是,需等待 retryAfter | 至少等待 retryAfter 秒再试,不要循环重试。 |
server_token | server_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),或为正确的应用签发。 |
business | verify_failed、wrong_answer、challenge_expired、max_attempts_reached | 是 | 用户答错或超时,组件会自动换题。除非你用 maxBusinessRefreshes 设了上限,否则无需处理。 |
network | 无响应、超时、5xx、未知错误码 | 是 | 临时问题。让 SDK 自动重试(retry: 'auto'),或提供“重试”按钮。 |
clock_skew | clock_skew_too_large | 是 | SDK 会自动校正一次设备时间。 |
expired | pass_token_expired | 是 | Web 2.0 验证条(animation: 'trace'):pass token 在表单使用前已过期,验证条提示用户重新验证,getValidate() 重新为空。 |
未知错误码一律按 network 处理,因此服务端新增的错误码不会让旧版 SDK 变成永久失败。
错误详情
Web。 onError 会收到第二个参数,getLastError() 返回同一个对象(React / Vue 封装只传第一个参数):
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
}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 | 错误字段 | 最近一次错误 |
|---|---|---|
| Android | CaptchalaError.errorClass、.retryable、.retryAfter、.reason、.attempt、.willRetry | CaptchalaClient.getLastError() |
| iOS / macOS | CaptchalaError.errorClass、.retryable、.retryAfter(Objective-C 可用 retryAfterSeconds,无值时为 -1)、.reason、.attempt、.willRetry | client.getLastError() |
| HarmonyOS | CaptchalaError.errorClass、.retryable、.retryAfter、.reason、.attempt、.willRetry | client.getLastError() |
| Electron | verify() reject 的错误和 onFail 的参数:err.code、err.class、err.retryable、err.retryAfter、err.reason、err.attempt、err.willRetry、err.errorLangKey | client.getLastError() |
| Flutter | CaptchalaError.errorClass、.retryable、.retryAfter、.reason、.attempt、.willRetry | await client.getLastError() |
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()
}
}重试选项
| 选项 | 取值 | 默认值 | 说明 |
|---|---|---|---|
retry | legacy / auto / never | legacy | legacy:与旧版 SDK 行为一致。auto:临时错误按退避自动重试(指数退避,最长 30 秒,±20% 抖动);retryAfter 不超过 60 秒的限流在等待结束后重试一次。never:不自动重试,立即上报错误。 |
retryInterval | 毫秒 | Web 1500,原生 1000 | 每次尝试之间的基础间隔。 |
retryMax | 数字 | 3 | Web:放弃前的网络尝试次数。原生:连接尝试次数(同 retryCount)。 |
retryBackoff | fixed / exponential | fixed;retry: 'auto' 时为 exponential | 间隔如何增长。 |
offlineFallback | 布尔 | Web true;原生 = enableOfflineMode(false) | 见离线兜底。 |
refreshExpired | manual / auto / never | 有 token provider 时 manual,否则 never | 见 Server token。 |
serverTokenProvider | 函数 | — | 从你的后端返回新的 server token。与 onServerTokenExpired 约定相同,两者都设置时以它为准;最多等待 10 秒。 |
maxBusinessRefreshes | 数字 | 不限 | 仅 Web。一次验证中答错达到该次数后不再换题,onError 以 business 分类触发。 |
showRetry | 布尔 | legacy 下为 false,否则 true | 仅 Web。临时错误时在错误卡片上显示“重试”按钮。 |
各平台的写法:
| 平台 | 设置方式 |
|---|---|
| Web | Captchala.init({ retry, retryInterval, retryMax, retryBackoff, offlineFallback, refreshExpired, serverTokenProvider, maxBusinessRefreshes, showRetry }) |
| React / Vue | 封装不传入这些选项;请直接使用 Web SDK(见 React、Vue) |
| Android | CaptchalaConfig.Builder().retry("auto").retryInterval(…).retryMax(…).retryBackoff(…).offlineFallback(…).refreshExpired(…).serverTokenProvider { … } |
| iOS / macOS | CaptchalaConfigBuilder().retry("auto").retryInterval(…).retryMax(…).retryBackoff(…).offlineFallback(…).refreshExpired(…).serverTokenProvider { … } |
| HarmonyOS | setRetry('auto')、setRetryInterval、setRetryMax、setRetryBackoff、setOfflineFallback、setRefreshExpired、setServerTokenProvider |
| Electron | new CaptchalaClient({ retry, retryInterval, retryMax, retryBackoff, offlineFallback, refreshExpired, serverTokenProvider }) |
| Flutter | CaptchalaConfig(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)。
| 默认值 | 关闭时 | |
|---|---|---|
| Web | offlineFallback: true(原有行为) | 达到 retryMax 次后错误交给 onError(showRetry 时显示“重试”按钮),不会离线通过 |
| 原生(Android、iOS、HarmonyOS、桌面端、Electron、Flutter) | offlineFallback = enableOfflineMode,默认 false | 失败即关闭(fail-closed):故障以 onError 结束,绝不会离线通过或给出 client-only 结果 |
服务端的明确回答(答错、限流、配置或 server token 错误)从不走离线路径。是否接受离线结果由你的后端决定, 见 Token 类型。
服务端返回的字段
CaptchaLa API 的错误回应保持原有错误码和结构,并新增 SDK 会透传的可选字段:
| 字段 | 出现于 | 含义 |
|---|---|---|
retryable | server_token_*、限流、too_many_failures | 同样的请求之后能否成功 |
retry_after | 限流(HTTP 429、签发限流)、too_many_failures | 下次请求前需等待的秒数 |
reason | server_token_invalid(expired / used / unknown)、server_token_exhausted(used) | token 被拒的原因 |
旧版 SDK 会忽略这些字段。