Choose and configure a proxy for CAPTCHA solving

Use a customer-supplied HTTP or HTTPS proxy. If your provider rotates exits, configure its session or pinning feature before creating the task, and keep that session for the final submission.

Don’t choose solely by labels such as residential, mobile or datacenter. Those labels don’t prove that the target will accept the request. Compare proxies using the actual solve-and-submit workflow; a successful connection alone doesn’t establish a CAPTCHA score.

http://USERNAME:[email protected]:8080
https://USERNAME:[email protected]:8443

Password p@ss:word becomes p%40ss%3Aword in the password component:
http://USERNAME:p%40ss%[email protected]:8080

Percent-encode reserved characters inside the username and password components separately. Don’t encode the entire URL: its scheme and separators must remain intact. The example shows how a password containing an at sign and colon belongs in the URL.

For proxyCandidates, each URL must have no path, query or fragment. Keep proxy passwords out of logs, including logs that print the full task request.

1. 1.

   Set exactly one proxy field

   In the task creation request, supply either proxy or proxyCandidates, never both. Use proxy for one known exit. Candidate lists accept at most six distinct URLs and let solvethree try alternative exits; they don’t guarantee that any candidate will work. Session tasks require a single proxy.

2. 2.

   Wait for a usable solution

   Poll while the task is pending or solving. Only ready contains a usable solution. Task creation or an HTTP success response isn’t a completed solve.

3. 3.

   Submit through the successful exit

   Use the successful proxy and the returned userAgent and secChUa when submitting the solution to its intended target. With candidates, don’t assume the first URL was the successful one. Don’t substitute an unrelated user agent, client hints or target URL.

If you need fallback exits, see proxy candidate selection. A single pinned proxy is simpler when you already know which exit your application will use.

Handle non-success HTTP responses before reading a success payload. A terminal task failure is a separate layer: when status is failed, stop polling and inspect errorCode and error.

HTTP 407

The proxy requires authentication. This isn’t solver API authentication or a target website login failure.

Try this: Verify the selected proxy’s credentials, credential encoding and provider routing without logging the password. Changing your solvethree API key won’t fix proxy authentication.

Your application can’t connect through the proxy

Check the URL’s scheme, hostname and port, then test connectivity through that proxy from the application’s environment.

Try this: Correct the endpoint or provider routing before creating another task. Keep connection failure separate from a response returned by the target.

The task fails with site-unreachable

Read the accompanying error and check whether the selected proxy can reach the intended target.

Try this: Correct the target or proxy configuration indicated by the failure before retrying. Don’t repeatedly submit unchanged invalid inputs or assume the problem is insufficient credit.

The task is ready, but the target rejects the request

Inspect the outgoing request for the correct solution, successful proxy, returned browser identity and intended target URL.

Try this: Correct mismatches before paying for another solve. A ready solution doesn’t guarantee acceptance by the target; continue with rejected-token diagnosis for reCAPTCHA.