{"record":{"id":"02c4f9239075eb7d","repo":"TeamNewPipe/NewPipe","slug":"recaptcha-challenge-requested","errorCode":null,"errorMessage":"reCaptcha Challenge requested","messagePattern":"reCaptcha Challenge requested","errorType":"exception","errorClass":"ReCaptchaException","httpStatus":429,"severity":"error","filePath":"app/src/main/java/org/schabi/newpipe/DownloaderImpl.java","lineNumber":164,"sourceCode":"                .url(url)\n                .addHeader(\"User-Agent\", USER_AGENT);\n\n        final String cookies = getCookies(url);\n        if (!cookies.isEmpty()) {\n            requestBuilder.addHeader(\"Cookie\", cookies);\n        }\n\n        headers.forEach((headerName, headerValueList) -> {\n            requestBuilder.removeHeader(headerName);\n            headerValueList.forEach(headerValue ->\n                    requestBuilder.addHeader(headerName, headerValue));\n        });\n\n        try (\n                okhttp3.Response response = client.newCall(requestBuilder.build()).execute()\n        ) {\n            if (response.code() == 429) {\n                throw new ReCaptchaException(\"reCaptcha Challenge requested\", url);\n            }\n\n            String responseBodyToReturn = null;\n            try (ResponseBody body = response.body()) {\n                responseBodyToReturn = body.string();\n            }\n\n            final String latestUrl = response.request().url().toString();\n            return new Response(\n                    response.code(),\n                    response.message(),\n                    response.headers().toMultimap(),\n                    responseBodyToReturn,\n                    latestUrl);\n        }\n    }\n}\n","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/TeamNewPipe/NewPipe/blob/9e8be091560a69f35d44bd252eb00bc7911c977b/app/src/main/java/org/schabi/newpipe/DownloaderImpl.java#L146-L182","documentation":"Thrown inside DownloaderImpl.execute when the OkHttp response status code is 429 (Too Many Requests). NewPipe interprets a 429 as the host (typically YouTube) issuing a reCaptcha challenge, so it raises a ReCaptchaException carrying the request URL. This exception is NewPipe's signal that the IP/account is rate-limited and human verification is required.","triggerScenarios":"Any HTTP request (GET/HEAD/POST) routed through DownloaderImpl.execute whose response code equals 429. Occurs after rapid successive requests to the same host, when using a shared/VPN IP that YouTube has flagged, or when cookies/headers identifying the session have expired and the host responds with a captcha wall.","commonSituations":"Excessive polling of YouTube pages (refreshing a feed repeatedly), running on an IP shared by many users, an outdated extractor that no longer sends the required cookies/headers YouTube expects, or regional blocks. Also seen when the YouTube restricted-mode cookie or consent cookies are missing/stale.","solutions":["Handle ReCaptchaException at the call site by launching the reCaptcha activity/flow so the user can solve the challenge and the resulting cookie is stored.","Reduce request frequency and add backoff/jitter for repeated fetches to the same host.","Ensure required cookies (consent, session, restricted-mode) are present and up to date via setCookie before retrying.","Update the NewPipe extractor to the latest version if YouTube changed its challenge mechanism, since header/cookie requirements shift over time.","Retry through a different network/IP if the current IP is flagged."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    final Response response = downloader.execute(request);\n    // use response\n} catch (final ReCaptchaException e) {\n    // launch reCaptcha solving flow, store resulting cookie, then retry\n}","preventionTips":["Rate-limit requests to a single host with backoff and jitter to avoid 429s.","Keep required cookies (consent, session, restricted-mode) current before making requests.","Handle ReCaptchaException at the UI layer to let the user solve the challenge and persist the resulting cookie.","Update the extractor regularly as YouTube's challenge/cookie requirements change."],"tags":["network","http","rate-limiting","recaptcha","downloader"],"backgroundTag":null,"analyzedSha":"9e8be091560a69f35d44bd252eb00bc7911c977b","analyzedAt":"2026-08-14T00:11:33.519Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}