--- title: 错误处理与重试 description: "CaptchaLa SDK 如何分类错误、哪些错误可以重试、可选的重试选项、server token 刷新、限流与离线兜底,覆盖 Web、Android、iOS、HarmonyOS、桌面端、Electron 与 Flutter。" --- # 错误处理与重试 所有 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`](../api-reference#server-token)),或为正确的应用签发。 | | `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 封装只传第一个参数): ```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 | 错误字段 | 最近一次错误 | | --- | --- | --- | | 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()` | ```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() } } ``` ## 重试选项 | 选项 | 取值 | 默认值 | 说明 | | --- | --- | --- | --- | | `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`) | 见[离线兜底](#offline-fallback)。 | | `refreshExpired` | `manual` / `auto` / `never` | 有 token provider 时 `manual`,否则 `never` | 见 [Server token](#server-tokens)。 | | `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](/zh-CN/sdk/react#web-sdk-options-not-passed)、[Vue](/zh-CN/sdk/vue#web-sdk-options-not-passed)) | | 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-tokens} 每次开始挑战都会消耗一次 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 的使用方式](../api-reference#server-token-usage)。 ## 限流 - 限流回应(HTTP 429 或限流错误码)以 `rate_limit` 类错误上报,带 `retryable` 和 `retryAfter`;SDK 默认不重试。 - `retry: 'auto'` 时,若等待时间不超过 60 秒,SDK 会等待 `retryAfter` 后**重试一次**;Web 的“重试”按钮会倒计时。 更长的等待直接上报。 - 不要在 `retryAfter` 结束前重试。 ## 离线兜底 {#offline-fallback} 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 类型](../api-reference#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 会忽略这些字段。