--- title: Handling errors and retries description: "How CaptchaLa SDKs classify errors, which ones can be retried, the opt-in retry options, server token refresh, rate limits and offline fallback, on web, Android, iOS, HarmonyOS, desktop, Electron and Flutter." --- # Handling errors and retries Every CaptchaLa SDK reports a failed verification with an error **code** and, from SDK 1.1.0 (web SDK 2.0.0), whether the error can be **retried**. The retry options are opt-in: if you set none of them, the SDK behaves exactly as before (`retry: 'legacy'`). ## Error classes Branch on the class. Every SDK maps the codes to the same classes and the same `retryable` value; the native SDKs name the field `errorClass` (`class` in Electron). | Class | Typical codes | Retryable | Recommended handling | | --- | --- | --- | --- | | `config` | `app_not_found`, `app_disabled`, `invalid_app_key`, `domain_not_allowed`, `pkg_not_allowed`, browser crypto unavailable | No | A setup problem. Don't retry. Log it and show a generic "verification unavailable" message; fix the app key, domain or package list in the dashboard. | | `blocked` | `ip_blocked` | No | Don't retry. Offer another way to continue (support contact, another verification method). | | `subscription` | `subscription_required`, `subscription_expired`, `subscription_inactive` | No | Check the plan in the dashboard. | | `rate_limit` | `ip_rate_limit_exceeded`, `app_rate_limit_exceeded`, `too_many_failures`, `qps_exceeded`, `rpm_exceeded`, `daily_limit_exceeded` | Yes, after `retryAfter` | Wait at least `retryAfter` seconds before the next attempt. Don't retry in a loop. | | `server_token` | `server_token_invalid`, `server_token_exhausted`, `server_token_required` | Yes, with a new token | Provide `serverTokenProvider` (or `onServerTokenExpired`); the SDK fetches a new token and retries. Without one, fetch a token and start again. | | `server_token` (binding) | `server_token_binding_mismatch`, `server_token_app_mismatch` | No | A new token has the same binding. Issue it without `bind_ip` (see [`bind_ip`](../api-reference#server-token)) or for the right app. | | `business` | `verify_failed`, `wrong_answer`, `challenge_expired`, `max_attempts_reached` | Yes | The user's answer was wrong or too late; the widget asks a new question by itself. Nothing to do unless you capped it with `maxBusinessRefreshes`. | | `network` | no answer, timeouts, 5xx, unknown codes | Yes | Temporary. Let the SDK retry (`retry: 'auto'`), or offer a Retry button. | | `clock_skew` | `clock_skew_too_large` | Yes | The SDK corrects the device clock once by itself. | | `expired` | `pass_token_expired` | Yes | Web 2.0 bar (`animation: 'trace'`): the pass token ran out before your form used it. The bar asks the user to verify again; `getValidate()` is empty. | Unknown codes are always treated as `network`, so a new server code never turns into a permanent failure in an older SDK. ## The error detail **Web.** `onError` receives a second argument, and `getLastError()` returns the same object (the React / Vue wrappers pass only the first argument): ```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); }); ``` **Native SDKs.** The error object passed to `onError` / `onFail` carries the same fields: `code`, `message`, `errorClass` (same values as `class`), `retryable`, `retryAfter` (seconds, or none), `reason`, `attempt` and `willRetry`. `getLastError()` returns the last one, or `null`. It is cleared when `verify()` starts and when a verification passes. On native, `attempt` counts the ticket requests of this verification: the first is 1, and each automatic new request (a rate-limit retry, a retry with a refreshed server token) adds 1. | SDK | Error fields | Last error | | --- | --- | --- | | Android | `CaptchalaError.errorClass`, `.retryable`, `.retryAfter`, `.reason`, `.attempt`, `.willRetry` | `CaptchalaClient.getLastError()` | | iOS / macOS | `CaptchalaError.errorClass`, `.retryable`, `.retryAfter` (`retryAfterSeconds` = -1 when absent, for Objective-C), `.reason`, `.attempt`, `.willRetry` | `client.getLastError()` | | HarmonyOS | `CaptchalaError.errorClass`, `.retryable`, `.retryAfter`, `.reason`, `.attempt`, `.willRetry` | `client.getLastError()` | | Electron | the rejected `verify()` error and the `onFail` argument: `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 options | Option | Values | Default | Meaning | | --- | --- | --- | --- | | `retry` | `legacy` / `auto` / `never` | `legacy` | `legacy`: behaviour of earlier SDKs. `auto`: temporary errors retry by themselves with a backoff (exponential, at most 30 s, ±20 % jitter); a rate limit whose `retryAfter` is at most 60 s is retried once after it has passed. `never`: no automatic retry; the error is reported at once. | | `retryInterval` | ms | web 1500, native 1000 | Base delay between attempts. | | `retryMax` | number | 3 | Web: network attempts before giving up. Native: connection attempts (same as `retryCount`). | | `retryBackoff` | `fixed` / `exponential` | `fixed`; `exponential` with `retry: 'auto'` | How the delay grows. | | `offlineFallback` | boolean | web `true`; native = `enableOfflineMode` (`false`) | See [Offline fallback](#offline-fallback). | | `refreshExpired` | `manual` / `auto` / `never` | `manual` with a token provider, else `never` | See [Server tokens](#server-tokens). | | `serverTokenProvider` | function | — | Returns a new server token from your backend. Same contract as `onServerTokenExpired` and wins when both are set. Awaited for at most 10 s. | | `maxBusinessRefreshes` | number | no limit | Web only. Stop asking new questions after this many wrong answers in one verification; `onError` then fires with class `business`. | | `showRetry` | boolean | `false` under `legacy`, else `true` | Web only. Show a Retry button on the error card for temporary errors. | Names per platform: | Platform | How to set them | | --- | --- | | Web | `Captchala.init({ retry, retryInterval, retryMax, retryBackoff, offlineFallback, refreshExpired, serverTokenProvider, maxBusinessRefreshes, showRetry })` | | React / Vue | Not passed by the wrappers; use the web SDK directly (see [React](/sdk/react#web-sdk-options-not-passed), [Vue](/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 tokens {#server-tokens} Every challenge start uses one use of the server token, including the starts the widget makes by itself (the refresh icon, closing and reopening, a new question after a wrong answer, `reset()` followed by `verify()`). A token issued with `max_uses=1` therefore fails on the second start unless you give the SDK a way to get a new one. - **`serverTokenProvider`** (or `onServerTokenExpired`): called when the server rejects the token. Return a new token from your backend; the SDK retries with it. Return `null` to give up. - **`refreshExpired`**: - `manual` (default with a provider): ask the provider after a rejection (web: once per `verify()`; native: up to 3 times per verification). - `auto`: also ask it before a restart that would reuse a token the previous attempt already spent, and (web) shortly before it expires when the provider returns `{ token, expiresIn }`. - `never`: never ask. - **`setServerToken(token)`** (every SDK except the React / Vue wrappers): replace the token directly, for example after you fetched one in `onError`, then call `verify()` again. The token is used by the next ticket request and replaces any token the provider returned earlier. You can call it before or between `verify()` calls and from any thread. It never starts a verification by itself. An empty token is ignored. - Binding and app mismatches are not refreshed under `retry: 'auto'` or `'never'`, because a new token would have the same binding. On the server, keep the default `max_uses` if your page can start the widget more than once, see [How a server token is used](../api-reference#server-token-usage). ## Rate limits - A rate-limit answer (HTTP 429, or a rate-limit code) is reported with class `rate_limit`, `retryable` and `retryAfter`; by default the SDK does not retry it. - With `retry: 'auto'` the SDK waits for `retryAfter` and retries **once** when the wait is at most 60 seconds; the web Retry button counts down until then. Longer waits are reported straight away. - Never retry before `retryAfter` has passed. ## Offline fallback {#offline-fallback} During a real outage of the CaptchaLa API the SDK can complete through a fallback path; the result is then marked offline (`offline` / `isOffline`, and `clientOnly` / `isClientOnly` when no service could be reached). | | Default | When it's off | | --- | --- | --- | | Web | `offlineFallback: true` (earlier behaviour) | After `retryMax` attempts the error goes to `onError` (with a Retry button when `showRetry`) instead of an offline pass | | Native (Android, iOS, HarmonyOS, desktop, Electron, Flutter) | `offlineFallback` = `enableOfflineMode`, `false` by default | **Fail-closed**: an outage ends in `onError`, never in an offline or client-only pass | A definite answer from the server (wrong answer, rate limit, configuration or server-token error) never goes offline. Your backend decides whether to accept offline results; see [Token types](../api-reference#token-types). ## What the server sends Error answers from the CaptchaLa API keep their codes and shape and add optional fields that the SDKs pass on: | Field | Sent with | Meaning | | --- | --- | --- | | `retryable` | `server_token_*`, rate limits, `too_many_failures` | Whether the same request can succeed later | | `retry_after` | rate limits (HTTP 429, issue rate limit), `too_many_failures` | Seconds to wait before the next request | | `reason` | `server_token_invalid` (`expired` / `used` / `unknown`), `server_token_exhausted` (`used`) | Why the token was rejected | Older SDKs ignore these fields.