How to Poll an Async CAPTCHA API Safely

Use a bounded polling loop, handle queued and uncertain states, and resume the same task after a client deadline.

For authorized QA automation and browser integration. Use only on websites and workflows you have permission to test.

HTTP success is not task completion

A create request returns HTTP 202 when a task is accepted. A successful GET returns HTTP 200 even while the task is queued. Read status before using solution.

Status	Client action
queued / dispatching / processing	Wait 2–3 seconds and GET the same task.
completed	Consume the solution in the authorized application.
failed / cancelled	Stop; inspect the task error and billing outcome.
uncertain	Preserve taskId, continue reconciliation or contact support. Do not create a replacement blindly.

A bounded polling loop

Set both a request timeout and an overall client deadline. The downloadable Python and Node.js clients use 20 seconds per request, up to 240 seconds overall, and a 3-second polling interval. These are example client budgets, not service-level guarantees.

save taskId
until client deadline:
    GET the same taskId
    completed -> return solution
    failed or cancelled -> stop
    queued, dispatching, processing or uncertain -> wait
on deadline -> persist taskId and stop local polling

Resume with that saved ID later. A client deadline neither cancels the task nor proves it failed. Do not POST a new task when a GET times out.

Requests that fail during polling

Treat transient GET errors separately from task status. For 429 and retryable 5xx, observe Retry-After and apply a bounded retry policy. If the required delay exceeds your budget, stop locally and retain the ID. Authentication and permission errors require correction, not tight polling.

Avoid overlapping pollers

One poller per task is normally sufficient. Store taskId in your job record, coordinate workers, and stop timers when a job ends. A Webhook can reduce polling; the API reference documents configuration and delivery behavior.

Why can a task remain uncertain?

The processing outcome may still require reconciliation. Funds can remain reserved. Query the original task and share its taskId and request ID with support; do not send your API Key. See billing and reservations.