Failover Behavior

This page explains what happens when TrustCaptcha — or the network path to it — is impaired or completely unavailable, and what you can do to keep your forms working through it.

We run a high-availability setup, so outages on our side are rare in practice. Two distinct failure modes can still happen, with very different mitigations:

The rest of this page walks through each scenario in detail.

This is the more likely of the two failure modes (though still uncommon): one of our internal services has a hiccup, but our public API gateway is still healthy. The gateway absorbs the problem on its own.

What you observe:

• Both the widget (when fetching its CAPTCHA config) and your backend (when fetching the verification result) continue to receive valid responses.
• The result you get back has decisionType set to FAILOVER or FAILOVER_TOLERANCE, and decisionAction set to ALLOW.
• The result also carries gatewayFailoverActive: true, so you can tell apart “regular pass” from “passed during a tolerant fallback”.

What you have to do: by default, nothing. Failover is on so the typical integrator does not need to think about outages — the user passes the form, the result is ALLOW, the flow continues.

For high-security integrations (banking, identity-critical flows), check the boolean flag:

if (verificationResult.isGatewayFailoverActive()) {
    // Reject, route to manual review, or step up — this result was synthesized during an outage.
}

The flag is purely metadata. It is true whenever the gateway produced the result through any of its failover paths (including an accepted client-failover claim from Scenario 2), false otherwise.

This is the worst case: our entire service is unreachable from both the user’s browser and your backend (DNS failure, our load balancer down, large-scale internet incident, …). Two things break at once:

• The widget bundle cannot be loaded from our CDN — without mitigation, the widget simply never renders.
• The widget runtime and your backend cannot reach our API — no token can be issued, and no result can be validated.

This scenario is exceptionally rare in practice, but if your forms have to keep working through it, three pieces have to be set up deliberately — none are on by default:

1. Self-host the widget bundle.
2. Enable widget-side failover.
3. Decide how your backend should react.

The following sub-sections walk through each step in detail.

Without this step, the bundle never loads from our CDN during an outage and there is nothing to fall back to — the widget simply doesn’t render. See Self-host the widget for the download links and a copy-and-paste setup.

By default the widget surfaces a COMMUNICATION_FAILURE error when our API is unreachable and refuses to produce a verification token. To opt in to failover behavior, set the failover-enabled attribute on the <trustcaptcha-component> — the widget then issues a clearly-marked client-failover token instead, and the user can submit the form normally.

<trustcaptcha-component
  sitekey="<your_site_key>"
  failover-enabled
></trustcaptcha-component>

This is a deliberate availability/security trade-off. Only enable it on forms where blocking real users during an outage is worse than letting through a small amount of unverified traffic — and always combine it with a server-side decision policy (see 2.3 below). CMS / no-code plugins typically expose a corresponding toggle (default off) that maps to this attribute. See the widget overview for the complete property reference.

Format of the client-failover token. When the widget falls back, it generates a self-built verification token with the same outer shape as a regular one, plus a clientFailover: true flag:

{ "verificationId": "<random uuid v4>", "expiresAt": "<now+15min>", "clientFailover": true }

(Base64-encoded as usual.) The widget treats this as a successful verification and emits captchaSolved. Whether to honor such a token is decided exclusively on the server side, not in the widget. When your backend validates it via one of our libraries, the request reaches our gateway with ?clientFailover=true. The gateway then decides:

• If the gateway has a recent outage on record (within its grace window, default 15 min): it returns a normal 200 OK result with decisionType=FAILOVER_TOLERANCE and decisionAction=ALLOW. The library hands you the result like any other success, with gatewayFailoverActive: true.
• If the gateway has no outage on record: it returns 412 PRECONDITION_FAILED. The library throws ClientReportedServerUnreachableException. The gateway never trusts a client claim alone — it only honors what its own observations support.

In a true outage your library can throw one of two failover exceptions. Both extend FailoverException, so you can catch them generically; the trust level is very different though, so most integrations should treat them separately.

Your backend could not reach our servers (connection error / timeout). This is a high-trust signal: a server-side observation, not something a malicious client can fake.

The widget claimed it couldn’t reach our servers, but your backend can. This is a low-trust signal because it depends on what the client browser reported.

There are two realistic explanations:

• Legitimate — there really was an outage on our side, the user solved the CAPTCHA in that window, and our gateway has since recovered. The widget reported failover correctly; the backend simply reaches us a moment later, after recovery. This will always happen at the tail end of every outage.
• Suspicious — the client has a local network problem (firewall, proxy, captive portal) and produced a failover token even though our service was reachable to everyone else. Or the client is intentionally faking a failover.

The pattern of catching both failover exceptions separately looks like this:

try {
    VerificationResult result = trustCaptcha.getVerificationResult(token);
    // Handle the result as you normally would.
} catch (ServerUnreachableException e) {
    // Example: allow + log.
} catch (ClientReportedServerUnreachableException e) {
    // Example: reject or soft-challenge.
}

try {
    const result = await trustCaptcha.getVerificationResult(token);
    // Handle the result as you normally would.
} catch (e) {
    if (e instanceof ServerUnreachableException) {
        // Example: allow + log.
    } else if (e instanceof ClientReportedServerUnreachableException) {
        // Example: reject or soft-challenge.
    }
}

try {
    $result = $trustCaptcha->getVerificationResult($token);
    // Handle the result as you normally would.
} catch (ServerUnreachableException $e) {
    // Example: allow + log.
} catch (ClientReportedServerUnreachableException $e) {
    // Example: reject or soft-challenge.
}

You can find detailed examples for every supported language on the respective Result Validation page (.NET, Go, JVM, Node.js, PHP, Python, Ruby, Rust).

Failover is only useful if it doesn’t silently become the new normal. Treat the following as a mandatory checklist:

1. Log every failover exception. Whether it’s ServerUnreachable… or ClientReportedServerUnreachable…, route it to your monitoring system. A sudden uptick is a signal — either we have an outage, or someone is probing your system.
2. Verify your egress firewall allows https://api.trustcomponent.com. Without it, every request will throw ServerUnreachableException and you won’t notice without monitoring.
3. Self-host the widget on the forms that need failover. Bundle the widget with your frontend assets and keep at least one previous version available for rollback.
4. Plugin / no-code users: the “Allow client-reported failover” toggle is off by default. Turn it on only as a deliberate decision, with a backend that handles ClientReportedServerUnreachableException correctly.
5. Custom REST integration: if you implement the result-retrieval call yourself, treat HTTP 412 and connection errors with the same logic the libraries do — see the Result Validation overview for the full status-code table.