TeamNewPipe/NewPipe · error · ReCaptchaException

reCaptcha Challenge requested

Error message

reCaptcha Challenge requested

What it means

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.

Source

Thrown at app/src/main/java/org/schabi/newpipe/DownloaderImpl.java:164

                .url(url)
                .addHeader("User-Agent", USER_AGENT);

        final String cookies = getCookies(url);
        if (!cookies.isEmpty()) {
            requestBuilder.addHeader("Cookie", cookies);
        }

        headers.forEach((headerName, headerValueList) -> {
            requestBuilder.removeHeader(headerName);
            headerValueList.forEach(headerValue ->
                    requestBuilder.addHeader(headerName, headerValue));
        });

        try (
                okhttp3.Response response = client.newCall(requestBuilder.build()).execute()
        ) {
            if (response.code() == 429) {
                throw new ReCaptchaException("reCaptcha Challenge requested", url);
            }

            String responseBodyToReturn = null;
            try (ResponseBody body = response.body()) {
                responseBodyToReturn = body.string();
            }

            final String latestUrl = response.request().url().toString();
            return new Response(
                    response.code(),
                    response.message(),
                    response.headers().toMultimap(),
                    responseBodyToReturn,
                    latestUrl);
        }
    }
}

View on GitHub (pinned to 9e8be09156)

Solutions

1. 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.
2. Reduce request frequency and add backoff/jitter for repeated fetches to the same host.
3. Ensure required cookies (consent, session, restricted-mode) are present and up to date via setCookie before retrying.
4. Update the NewPipe extractor to the latest version if YouTube changed its challenge mechanism, since header/cookie requirements shift over time.
5. Retry through a different network/IP if the current IP is flagged.

try {
    final Response response = downloader.execute(request);
    // use response
} catch (final ReCaptchaException e) {
    // launch reCaptcha solving flow, store resulting cookie, then retry
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid content length
• ERROR_CODE_IO_NETWORK_CONNECTION_FAILED

AI-assisted analysis of TeamNewPipe/NewPipe@9e8be09156 (2026-08-14). Data as JSON: /api/errors/02c4f9239075eb7d. Report an issue: GitHub.