Operations
Planning for a CAPTCHA provider outage
Keep server policy enforced, visitors informed, and operational diagnosis distinct when a verifier becomes unavailable.
By the easycaptcha team · Published
A verifier outage does not establish that a submitted proof is valid. Decide how the application handles unavailable verification before an exception handler is forced to choose. A broad catch that returns success can turn an availability problem into removal of the endpoint’s requirement.
Outage policy
Keep the protected action, retry behavior, and assistance route explicit. The application owner must decide the policy; a client should not select a weaker proof merely because one widget failed.
Diagnose the actual dependency
Missing credentials, blocked scripts, an unavailable state store, an external timeout, and malformed provider output are different causes. Restricted logs can record the stage, configuration version, and correlation identifiers without printing secrets or complete proofs.
A visible widget does not prove the server verifier works. A server health response does not prove a protected user journey completes. Use checks suited to each boundary.
Preserve useful recovery
Retain appropriate non-sensitive form content and explain whether a visitor should retry or use an independent assistance path. Avoid indefinite spinners and buttons that stay disabled after a definite failure.
Test whether support depends on the same unavailable provider. An alternative that repeats the failed verification may be operationally useless even though the page has a contact link.
Reconcile accepted actions after recovery
An interrupted response can leave the original application’s acceptance unknown. Before prompting a new submission, use the service’s supported receipt or state mechanism where available. A fresh proof does not show that the old action was never accepted.
For solving integrations, retain known task IDs and distinguish uncertain creation from a failed lookup. Do not flood the provider with replacement work during recovery.
Make the incident report actionable
Document affected operations, first observed failure, configuration changes, visitor impact, and known recovery. Report legitimate completions and unresolved tasks rather than only the number of errors.
Fail-closed verification states the endpoint boundary, support-assisted completion makes the alternative practical, and owned-flow monitoring separates availability checks from end-to-end evidence so one green indicator cannot hide a broken journey.
Frequently asked questions
What should my application do when verification is unavailable?
Apply the operation's defined outage policy, preserve appropriate visitor state, and provide a clear recovery path.
Should an uncertain job lookup create a replacement immediately?
Preserve the task ID and investigate its state first. Recreating work after a transport uncertainty can duplicate paid submissions.
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.