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) 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):
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);
});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() |
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. |
refreshExpired | manual / auto / never | manual with a token provider, else never | See 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, 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 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(oronServerTokenExpired): called when the server rejects the token. Return a new token from your backend; the SDK retries with it. Returnnullto give up.refreshExpired:manual(default with a provider): ask the provider after a rejection (web: once perverify(); 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 inonError, then callverify()again. The token is used by the next ticket request and replaces any token the provider returned earlier. You can call it before or betweenverify()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.
Rate limits
- A rate-limit answer (HTTP 429, or a rate-limit code) is reported with class
rate_limit,retryableandretryAfter; by default the SDK does not retry it. - With
retry: 'auto'the SDK waits forretryAfterand 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
retryAfterhas passed.
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.
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.