Move a CapSolver reCAPTCHA integration to solvethree

solvethree defaults to reCAPTCHA v3 Enterprise and also accepts standard v3. Its other public products are Kasada and Ticketmaster TMPT. It doesn’t support reCAPTCHA v2, hCaptcha, Turnstile or browser-extension solving, so this isn’t a universal replacement for every CapSolver integration.

Before sending a reCAPTCHA task, set up the target site in the console and make sure an active profile is available to your workspace. Sending a hostname and action doesn’t create that profile. Don’t remove CapSolver’s websiteKey field and assume the remaining request is sufficient.

The starting request uses CapSolver’s clientKey and provider-specific task envelope:

{
  "clientKey": "CAPSOLVER_API_KEY",
  "task": {
    "type": "ReCaptchaV3Task",
    "websiteURL": "https://accounts.example.com/login",
    "websiteKey": "PUBLIC_SITE_KEY",
    "pageAction": "login",
    "isEnterprise": true,
    "proxy": "http://user:[email protected]:8080"
  }
}

For solvethree, send the flat body below to POST https://api.solvethree.com/v1/tasks. Set the Authorization header to Bearer followed by your workspace API key. Keep that key on the server; don’t carry clientKey into the new JSON body.

{
  "site": "accounts.example.com",
  "action": "login",
  "proxy": "http://user:[email protected]:8080",
  "requestId": "example_login_001"
}

The example is an Enterprise request because it leaves recaptchaType at its default. Select standard v3 explicitly when that’s what your target uses; don’t translate every CapSolver task type to the Enterprise default.

A CapSolver ProxyLess task has no direct proxyless equivalent here: solvethree requires a caller-supplied proxy input. If your current integration doesn’t manage a proxy, that’s an integration change, not a field rename. Don’t copy a SOCKS proxy configuration into the new request either; solvethree accepts HTTP and HTTPS proxy URLs.

Start with a single proxy so the route used for solving and submission is unambiguous. If you use proxyCandidates instead, supply at most six distinct HTTP or HTTPS proxy URLs without paths, queries or fragments. Candidates let the service try alternative egress; they don’t guarantee that a proxy or target will work.

CapSolver retrieves asynchronous results through getTaskResult with clientKey and taskId. solvethree retrieves them through Bearer-authenticated GET /v1/tasks/:id. Update the result parser as well as the HTTP call; CapSolver’s status and error fields belong to a different contract.

1. 1.

   Check the HTTP response first

   Handle non-success HTTP responses before reading a success payload. An HTTP request error and a failed solving task need separate handling.

2. 2.

   Inspect the task returned by creation

   reCAPTCHA creation waits up to 15 seconds by default, so the response may already be terminal. Only ready contains a usable solution. If the task is pending or solving, retrieve it using its returned solvethree task ID.

3. 3.

   Stop polling at ready or failed

   For ready, pass the solution to your submission code. For failed, inspect errorCode and error and stop polling that task. Failed solves are refunded. Don’t blindly retry unchanged invalid inputs or assume every failure means insufficient credit.

During a staged migration, keep each task ID tagged with its provider. Finish existing CapSolver tasks through CapSolver and route new solvethree tasks through solvethree. Normalize their outcomes in your adapter rather than sending an old provider’s task ID to the new API.

Use solution.token when submitting the reCAPTCHA result to the intended target. Also retain the returned userAgent and secChUa, and use the successful proxy for submission. If your existing adapter returns only a token string, change it to carry that information through to the submitting client.

If a ready token is rejected, inspect the outgoing application request before paying for another solve. Check that it contains the new token—not a task ID or an old token—and that submission uses the returned browser identity, the successful proxy and the intended target URL. A ready task means a solution was generated, not that the target accepted your subsequent request.

The after example includes requestId for recovery. Generate one for each new logical task and keep it with the exact request inputs. It must contain 1–64 ASCII letters, numbers, underscores or hyphens. Reusing it with the same task request returns the existing task; using it with different inputs conflicts.

If creation times out, retrieve the task if you have its ID, or resubmit the same body with the same requestId. A lost response doesn’t prove creation failed. Don’t generate a fresh ID merely because your client stopped waiting.

Allow for reCAPTCHA’s default creation wait of up to 15 seconds plus network overhead in your client timeout. GET polling returns without waiting by default and accepts waitMs up to 15000. Put waitMs in the URL query, not the task JSON, and allow for that wait in the polling timeout too.