Skip to content

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).

ClassTypical codesRetryableRecommended handling
configapp_not_found, app_disabled, invalid_app_key, domain_not_allowed, pkg_not_allowed, browser crypto unavailableNoA 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.
blockedip_blockedNoDon't retry. Offer another way to continue (support contact, another verification method).
subscriptionsubscription_required, subscription_expired, subscription_inactiveNoCheck the plan in the dashboard.
rate_limitip_rate_limit_exceeded, app_rate_limit_exceeded, too_many_failures, qps_exceeded, rpm_exceeded, daily_limit_exceededYes, after retryAfterWait at least retryAfter seconds before the next attempt. Don't retry in a loop.
server_tokenserver_token_invalid, server_token_exhausted, server_token_requiredYes, with a new tokenProvide 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_mismatchNoA new token has the same binding. Issue it without bind_ip (see bind_ip) or for the right app.
businessverify_failed, wrong_answer, challenge_expired, max_attempts_reachedYesThe 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.
networkno answer, timeouts, 5xx, unknown codesYesTemporary. Let the SDK retry (retry: 'auto'), or offer a Retry button.
clock_skewclock_skew_too_largeYesThe SDK corrects the device clock once by itself.
expiredpass_token_expiredYesWeb 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.

SDKError fieldsLast error
AndroidCaptchalaError.errorClass, .retryable, .retryAfter, .reason, .attempt, .willRetryCaptchalaClient.getLastError()
iOS / macOSCaptchalaError.errorClass, .retryable, .retryAfter (retryAfterSeconds = -1 when absent, for Objective-C), .reason, .attempt, .willRetryclient.getLastError()
HarmonyOSCaptchalaError.errorClass, .retryable, .retryAfter, .reason, .attempt, .willRetryclient.getLastError()
Electronthe rejected verify() error and the onFail argument: 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()
    }
}

Retry options ​

OptionValuesDefaultMeaning
retrylegacy / auto / neverlegacylegacy: 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.
retryIntervalmsweb 1500, native 1000Base delay between attempts.
retryMaxnumber3Web: network attempts before giving up. Native: connection attempts (same as retryCount).
retryBackofffixed / exponentialfixed; exponential with retry: 'auto'How the delay grows.
offlineFallbackbooleanweb true; native = enableOfflineMode (false)See Offline fallback.
refreshExpiredmanual / auto / nevermanual with a token provider, else neverSee Server tokens.
serverTokenProviderfunction—Returns a new server token from your backend. Same contract as onServerTokenExpired and wins when both are set. Awaited for at most 10 s.
maxBusinessRefreshesnumberno limitWeb only. Stop asking new questions after this many wrong answers in one verification; onError then fires with class business.
showRetrybooleanfalse under legacy, else trueWeb only. Show a Retry button on the error card for temporary errors.

Names per platform:

PlatformHow to set them
WebCaptchala.init({ retry, retryInterval, retryMax, retryBackoff, offlineFallback, refreshExpired, serverTokenProvider, maxBusinessRefreshes, showRetry })
React / VueNot passed by the wrappers; use the web SDK directly (see 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 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.

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 ​

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).

DefaultWhen it's off
WebofflineFallback: 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 defaultFail-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:

FieldSent withMeaning
retryableserver_token_*, rate limits, too_many_failuresWhether the same request can succeed later
retry_afterrate limits (HTTP 429, issue rate limit), too_many_failuresSeconds to wait before the next request
reasonserver_token_invalid (expired / used / unknown), server_token_exhausted (used)Why the token was rejected

Older SDKs ignore these fields.

MIT-licensed examples · CaptchaLa is operated independently