Verification fundamentals
Fail-closed CAPTCHA verification and usable recovery
Prevent missing configuration or provider errors from authorizing an action, while preserving clear retries and non-sensitive form content for genuine visitors.
By the easycaptcha team · Published
A provider timeout, missing secret, or malformed response does not establish that verification passed. Treat failure to obtain a valid decision according to the server’s policy as a failure to satisfy that condition. Otherwise an outage can become an accidental authorization path.
Verification during outages
Keep this rule visible in your error handling. A broad exception catch that returns true may appear to preserve availability while silently removing the protected endpoint’s requirement.
Distinguish causes without exposing secrets
Record whether the problem was configuration, connectivity, response parsing, or explicit proof rejection. A user can receive a concise retry or availability message while restricted operational logs retain the stage and request ID.
Never include the secret value or complete proof in a configuration error. The useful information is which setting or dependency needs attention, not its credential contents.
Keep recovery usable
Preserve non-sensitive form input and make the retry action reachable by keyboard and assistive technology. Avoid an indefinite spinner or a button that stays disabled after a definite failure. A valid retry should obtain fresh verification rather than resend a stale value.
If a support route is intended as an alternative, examine whether it relies on the same unavailable provider. A fallback that repeats the broken dependency is not operationally independent.
Test policy before deploying
Stop or mock the provider, supply malformed output, remove test configuration, and send a direct request without a proof. Confirm that protected work does not occur. Separately test recovery after the dependency becomes available again.
For multi-provider flows, keep the required policy on the server. The client should not skip one requirement because another widget succeeded. The server-validation guide covers the endpoint boundary; outage planning covers operational response, and accessibility covers how visitors discover and complete the next step.
Frequently asked questions
What does failing closed mean for verification?
When required verification is unavailable or unsuccessful, the protected operation does not proceed as if verification had succeeded.
How can a fail-closed flow remain usable?
Preserve the visitor's work, explain the failure, and provide a retry or support path while retaining the protected operation's policy.
How can easycaptcha fit into my integration tests?
Use the documented recognition or token API for the hCaptcha stage, preserve task IDs, and inspect terminal results. Measure verifier acceptance and application completion separately from job completion.