{"record":{"id":"8bccce28d1199c25","repo":"searxng/searxng","slug":"cloudflare-captcha","errorCode":null,"errorMessage":"Cloudflare CAPTCHA","messagePattern":"Cloudflare CAPTCHA","errorType":"exception","errorClass":"SearxEngineCaptchaException","httpStatus":null,"severity":"error","filePath":"searx/network/raise_for_httperror.py","lineNumber":38,"sourceCode":"            and 'orchestrate/jsch/v1' in resp.text\n            and 'window._cf_chl_enter(' in resp.text\n        ):\n            return True\n    if resp.status_code == 403 and '__cf_chl_captcha_tk__=' in resp.text:\n        return True\n    return False\n\n\ndef is_cloudflare_firewall(resp: \"SXNG_Response\"):\n    return resp.status_code == 403 and '<span class=\"cf-error-code\">1020</span>' in resp.text\n\n\ndef raise_for_cloudflare_captcha(resp: \"SXNG_Response\"):\n    if resp.headers.get('Server', '').startswith('cloudflare'):\n        if is_cloudflare_challenge(resp):\n            # https://support.cloudflare.com/hc/en-us/articles/200170136-Understanding-Cloudflare-Challenge-Passage-Captcha-\n            # suspend for 2 weeks\n            raise SearxEngineCaptchaException(\n                message='Cloudflare CAPTCHA', suspended_time=get_setting('search.suspended_times.cf_SearxEngineCaptcha')\n            )\n\n        if is_cloudflare_firewall(resp):\n            raise SearxEngineAccessDeniedException(\n                message='Cloudflare Firewall',\n                suspended_time=get_setting('search.suspended_times.cf_SearxEngineAccessDenied'),\n            )\n\n\ndef raise_for_recaptcha(resp: \"SXNG_Response\"):\n    if resp.status_code == 503 and '\"https://www.google.com/recaptcha/' in resp.text:\n        raise SearxEngineCaptchaException(\n            message='ReCAPTCHA', suspended_time=get_setting('search.suspended_times.recaptcha_SearxEngineCaptcha')\n        )\n\n\ndef raise_for_captcha(resp: \"SXNG_Response\"):","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/searxng/searxng/blob/9fea41204fdfa7a5cfa15b0ebd12904c520478ce/searx/network/raise_for_httperror.py#L20-L56","documentation":"After an HTTP >=400 response, if the Server header starts with 'cloudflare' and the body matches a Cloudflare challenge/CAPTCHA page, SearxEngineCaptchaException is raised and the engine is suspended (default 2 weeks per suspended_times.cf_SearxEngineCaptcha).","triggerScenarios":"An engine behind Cloudflare returns a challenge page (403/503 with cf challenge markers) during search.","commonSituations":"Engines like certain scrape-based ones getting challenged due to datacenter IPs or rate limits; no impact from user config.","solutions":["Wait out the suspension or restart to clear it","Route that engine's traffic through a residential proxy (outgoing.proxies / per-engine networks)","Reduce request rate for the affected engine"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":"def is_cloudflare_challenge_resp(resp) -> bool:\n    return resp.headers.get('Server', '').startswith('cloudflare') and is_cloudflare_challenge(resp)","tryCatchPattern":"try:\n    search(...)\nexcept SearxEngineCaptchaException as e:\n    suspend_and_use_backup_engine(e.suspended_time)","preventionTips":["Use residential proxies for Cloudflare-fronted engines","Keep request rates modest","Keep a second engine for the same category"],"tags":["cloudflare","captcha","engine","network"],"backgroundTag":"cloudflare-challenge","analyzedSha":"9fea41204fdfa7a5cfa15b0ebd12904c520478ce","analyzedAt":"2026-08-27T06:40:00.395Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}