Use a residential proxy in Java with OkHttp: proxy, authenticator, and a first check

This guide connects Java with OkHttp to a residential proxy and verifies one authorized request. Copy the actual protocol, host, port, username, and password from the console. The values below are deliberately fake: host proxy.example.invalid, port 10000, username USER_EXAMPLE, password PASS_EXAMPLE_NOT_REAL. Not for mainland China.

Choose rotating residential for changing exits and traffic billing, or static residential when one exit must stay fixed for the order term. A sticky session is not a static IP.

Map the console fields

Set the gateway with OkHttp proxy, then answer proxy challenges with proxyAuthenticator and Credentials.basic. Do not put credentials in the host field.

Minimal example

import java.net.InetSocketAddress;
import java.net.Proxy;
import okhttp3.Credentials;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

Proxy proxy = new Proxy(Proxy.Type.HTTP,
    new InetSocketAddress("proxy.example.invalid", 10000));

OkHttpClient client = new OkHttpClient.Builder()
    .proxy(proxy)
    .proxyAuthenticator((route, response) -> response.request().newBuilder()
        .header("Proxy-Authorization",
            Credentials.basic("USER_EXAMPLE", "PASS_EXAMPLE_NOT_REAL"))
        .build())
    .build();

Request request = new Request.Builder().url("https://example.com/").build();
try (Response response = client.newCall(request).execute()) {
    System.out.println(response.code());
}

This example is for OkHttp. Java 11 HttpClient uses a different proxy selector and authenticator API, so do not paste the OkHttp builder calls into it. The target in the snippet is only a connectivity placeholder; replace it with a page you are authorized to access. For a source-IP check, use an approved endpoint that displays the request IP.

First-check sequence

For field shapes, see proxy format, HTTP / SOCKS5 setup, Docs quickstart, and 407 / timeout troubleshooting.

FAQ

What does HTTP 407 mean?

The gateway reached your client but rejected or did not receive proxy authentication. Re-copy the username and password from the console and keep them in the authentication fields.

Why does the request time out?

Check protocol, host, port, local firewall, DNS, and the authorized target. Then reduce the test to one request with a finite timeout.

Should the host include the protocol?

No. Keep the host as a hostname. Add the scheme only where the library expects a proxy URL.

Can I use SOCKS5 with this exact example?

Not necessarily. This Java with OkHttp example demonstrates an HTTP proxy. Use the protocol returned by the console and the library-specific SOCKS adapter when required.

How do I confirm the exit?

Request an authorized page that reports the source IP, compare it with your intended region or static order, and do not treat a gateway hostname as the exit.

Can a sticky session replace a static IP?

No. Sticky keeps a rotating exit for a limited window when available; a static residential order keeps its assigned exit for the order term.

May I use these placeholder credentials?

No. The example domain cannot resolve and every credential shown here is fake. Copy current values from the console.

Can I use this in mainland China?

No. ZTProxy proxy services are not supported for use in mainland China. Use only lawful, authorized targets.

Next steps

1. Copy the current gateway and auth from the console.
2. Run the example against one authorized target.
3. Confirm the exit, then add retries and concurrency gradually. Compare other clients: Python, Node.js and Axios, and PHP and Guzzle.