API reference

Endpoint#

The call is synchronous: it holds open until the challenge is solved or fails, then returns the finished result. Nothing to poll, no job id to store — for most integrations this is the whole API.

Request#

The task object#

task.type decides which fields the rest of the object takes. Pick a type below and both the field table and the code sample update — the URL fragment changes too, so you can link someone straight to the variant they need.

# pip install voidcaptcha
from voidcaptcha import VoidCaptcha

client = VoidCaptcha("void_a1b2c3d4e5f60718293a4b5c6d7e8f90")

result = client.recaptcha_v3(
    url="https://example.com/login",
    site_key="6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696",
    action="login",
    proxy="proxy.example.com:9090:user:pass",
)

print(result.value)

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "03AGdBq25V6…",
    "userAgent": "Mozilla/5.0 …"
  },
  "cost": "$0.0008",
  "balance": "$411.24",
  "elapsedMs": 4820
}

Response#

Check errorId rather than the HTTP status. A solve that fails for a reason on the target’s side — a blocked IP, an unsolvable challenge, a timeout — answers 200 with a non-zero errorId: it is a well-formed response describing a failure, not a transport error, and nothing is charged for it. A status outside 2xx means the call did not go through at all — a bad key, a malformed request, an empty balance or a thread limit.

The asynchronous pair#

Some fleets cannot hold a connection open for the length of a solve — a serverless function with a short ceiling, or a worker that must not block on one task. Those hand the task over and collect it later. Same envelope, same task object, same error codes; only the shape of the wait changes.

The body is exactly what you would have posted to /v1/getResult. The response returns as soon as the task is accepted, not when it is finished.

/v1/checkTask answers with status: "processing" while the solve is still running, and with the same finished envelope the synchronous call returns — solution, cost, balance — once it is not. Poll no faster than every two seconds; a tighter loop earns ERROR_RATE_LIMITED and does not make the solve arrive sooner.

// POST /v1/createTask
{ "clientKey": "void_a1b2c3d4e5f60718293a4b5c6d7e8f90", "task": { "type": "ReCaptchaV3", "...": "..." } }
→ { "errorId": 0, "status": "processing", "taskId": "vt_8f3c1d92a4b7" }

// POST /v1/checkTask
{ "clientKey": "void_a1b2c3d4e5f60718293a4b5c6d7e8f90", "taskId": "vt_8f3c1d92a4b7" }
→ { "errorId": 0, "status": "processing" }
→ { "errorId": 0, "status": "ready", "solution": { "token": "03AGdBq25V6…" } }

Rate limits#

Accounts are limited by concurrent solves in flight rather than by requests per second, which suits a synchronous API better. The default is ten; exceeding it returns ERROR_THREAD_LIMIT with HTTP 429. Ask support to raise it and mention the throughput you need.

Idempotency#

Solves are not idempotent — each call performs real work against the target and is charged on success. Do not blind-retry a request that timed out client-side without checking whether it actually completed; use softId to correlate.

Errors#

Failures carry a numeric errorId, a stable errorCode string and a description. The error reference lists every code together with whether retrying is worth attempting.