How to Solve Queue-it CAPTCHA

TL;DR

• Current Queue-it CAPTCHA integrations should be handled as BotDeflector workflows, not as plain text recognition.
• Use AntiBotdeflectorTaskProxyLess when you have the page URL, BotDeflector domain, and challenge flowToken; the asynchronous result is returned in solution.token.
• Use VisionEngine with module: "botdeflector" only for a visual challenge that provides foreground and background images; this request returns recognition coordinates directly.
• websiteURL and domain are separate BotDeflector fields and may contain different hostnames. Capture both from the authorized browser session.
• Keep the Queue-it browser session open while solving because the returned result belongs to the challenge context that produced the inputs.
• Use this workflow only on Queue-it implementations you own, test, or have explicit permission to automate.

Queue-it virtual waiting rooms control access during traffic spikes such as ticket releases, product launches, and limited-inventory events. The CAPTCHA step used in current integrations is more than a picture containing characters: BotDeflector supplies a challenge flow that can require either a token result or visual coordinates.

This updated guide explains both supported paths with CapSolver. The token path is the default integration for a captured flowToken; the VisionEngine path applies when the browser exposes the corresponding foreground and background challenge images. CapSolver's CAPTCHA API documentation guide explains the shared task lifecycle and error model.

What Changed in the Queue-it CAPTCHA Flow?

The current Queue-it workflow should be modeled as BotDeflector rather than a standalone OCR form. A BotDeflector challenge contains session-bound inputs, and the expected output depends on the integration path:

These modes are not interchangeable. Token mode does not accept a Base64 image as a substitute for flowToken, while visual recognition mode does not return the final BotDeflector token. Inspect the challenge implementation in your authorized browser session and choose the path matching the data available there.

Queue-it's traffic waiting room and the CAPTCHA solver also use different queues. The waiting room determines when a visitor may continue, while the CapSolver API processes a challenge task. The request queue glossary provides useful background for separating application queueing from API task polling.

Prerequisites

Prepare the following before creating a task:

• A CapSolver API key stored in an environment variable or secrets manager.
• A Queue-it page and BotDeflector challenge that you are authorized to test.
• The exact page URL where the challenge appears.
• For token mode: the BotDeflector domain and current flowToken captured from the same browser session.
• For visual mode: Base64-encoded foreground and background challenge images.
• An HTTP client that can send JSON requests to https://api.capsolver.com.

Do not place a production API key directly in source code. The examples use YOUR_API_KEY, FLOW_TOKEN_FROM_PAGE, and example domains as placeholders.

How to Solve Queue-it BotDeflector in Token Mode

Token mode uses AntiBotdeflectorTaskProxyLess, then polls getTaskResult until CapSolver returns solution.token. The field names and response shape follow the current BotDeflector token-mode documentation.

Step 1: Capture the BotDeflector inputs

Capture these values from the same authorized browser session:

• websiteURL: the full page URL where the BotDeflector challenge is running.
• domain: the BotDeflector domain required by that challenge.
• flowToken: the current challenge token exposed by the BotDeflector flow.

Do not assume domain is simply the hostname from websiteURL. The official task definition treats them as separate inputs, and they may not use the same domain name.

Step 2: Create the token task

Send the captured values to createTask:

curl --request POST 'https://api.capsolver.com/createTask' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "AntiBotdeflectorTaskProxyLess",
      "websiteURL": "https://queue.example.com/waitingroom/",
      "domain": "challenge.example.net",
      "flowToken": "FLOW_TOKEN_FROM_PAGE"
    }
  }'

A successful creation response contains a task ID:

{
  "errorId": 0,
  "errorCode": "",
  "errorDescription": "",
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

Check errorId before storing taskId. If task creation fails, log errorCode and errorDescription without recording the API key or full challenge token.

Step 3: Poll for the BotDeflector token

Send the returned task ID to getTaskResult:

curl --request POST 'https://api.capsolver.com/getTaskResult' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
  }'

Continue polling while the response status is processing. Stop immediately if the API returns a nonzero errorId or a failed status. When the task is ready, read the token from solution.token:

{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006",
  "status": "ready",
  "solution": {
    "token": "BOTDEFLECTOR_TOKEN"
  }
}

Step 4: Return the token to the same browser flow

Pass the returned token to the BotDeflector integration point used by the same Queue-it browser session. Do not create a fresh browser context between capturing flowToken and applying the result. Session changes, navigation, or challenge refreshes can invalidate the context and require a new task.

The exact injection or submission point belongs to the Queue-it implementation you are testing. Capture it from your own application integration instead of relying on a universal selector.

Redeem Your CapSolver Bonus Code

Boost your automation budget instantly!
Use bonus code CAP26 when topping up your CapSolver account to get an extra 5% bonus on every recharge — with no limits.
Redeem it now in your CapSolver Dashboard

Complete Python Example for Token Mode

The following example creates a BotDeflector task, polls with a bounded timeout, and returns solution.token. It uses placeholder challenge values because a real flowToken must come from your authorized browser session.

import os
import time

import requests


API_BASE = "https://api.capsolver.com"
API_KEY = os.environ["CAPSOLVER_API_KEY"]


def solve_botdeflector(website_url, domain, flow_token, timeout=120):
    create_response = requests.post(
        f"{API_BASE}/createTask",
        json={
            "clientKey": API_KEY,
            "task": {
                "type": "AntiBotdeflectorTaskProxyLess",
                "websiteURL": website_url,
                "domain": domain,
                "flowToken": flow_token,
            },
        },
        timeout=30,
    )
    create_response.raise_for_status()
    created = create_response.json()

    if created.get("errorId"):
        raise RuntimeError(
            f"createTask failed: {created.get('errorCode')} - "
            f"{created.get('errorDescription')}"
        )

    task_id = created["taskId"]
    deadline = time.monotonic() + timeout

    while time.monotonic() < deadline:
        time.sleep(2)
        result_response = requests.post(
            f"{API_BASE}/getTaskResult",
            json={"clientKey": API_KEY, "taskId": task_id},
            timeout=30,
        )
        result_response.raise_for_status()
        result = result_response.json()

        if result.get("errorId"):
            raise RuntimeError(
                f"getTaskResult failed: {result.get('errorCode')} - "
                f"{result.get('errorDescription')}"
            )

        if result.get("status") == "ready":
            return result["solution"]["token"]

        if result.get("status") == "failed":
            raise RuntimeError("BotDeflector task failed")

    raise TimeoutError(f"BotDeflector task {task_id} exceeded {timeout}s")


token = solve_botdeflector(
    website_url="https://queue.example.com/waitingroom/",
    domain="challenge.example.net",
    flow_token="FLOW_TOKEN_FROM_PAGE",
)
print(token)

For more detail on environment variables, request handling, and reusable client structure, see the Python CAPTCHA API integration guide.

When to Use VisionEngine for a Queue-it BotDeflector Challenge

Use VisionEngine only when the challenge exposes the visual assets required by the BotDeflector recognition module. This path accepts a foreground image and an imageBackground, then returns click coordinates in the initial createTask response.

The request uses type: "VisionEngine" and module: "botdeflector":

curl --request POST 'https://api.capsolver.com/createTask' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "VisionEngine",
      "module": "botdeflector",
      "image": "BASE64_FOREGROUND_IMAGE",
      "imageBackground": "BASE64_BACKGROUND_IMAGE",
      "websiteURL": "https://queue.example.com/waitingroom/"
    }
  }'

According to the current VisionEngine documentation, this task returns recognition data directly; it does not require a separate getTaskResult request. A successful response has this shape:

{
  "errorId": 0,
  "errorCode": "",
  "errorDescription": "",
  "status": "ready",
  "solution": {
    "points": [[123, 88], [244, 84], [174, 70]]
  },
  "taskId": "TASK_ID"
}

Apply the returned points to the visual challenge in the same coordinate space as the submitted images. Scaling, cropping, or using a screenshot with different dimensions can move the target positions and cause incorrect interactions.

VisionEngine handles the recognition step; it does not replace the surrounding browser state management. If the page expects a subsequent token exchange, continue that exchange inside the same authorized session.

Common Queue-it BotDeflector Integration Problems

The task is created but never becomes ready

Confirm that the flowToken is current and belongs to the same page session. Also verify that websiteURL and domain were captured independently rather than constructed from one hostname. Use bounded polling and stop on API errors instead of looping indefinitely.

The returned token is rejected

A rejected token commonly indicates that the page state changed after the challenge inputs were captured. Keep cookies, browser context, URL, and challenge state stable until the result is applied. If the challenge refreshes, capture a new flowToken and create a new task.

VisionEngine returns points but the clicks miss

Send the original challenge images without resizing them, and apply the coordinates against the same dimensions. Check whether your browser automation introduced device-pixel-ratio scaling, CSS resizing, or a cropped screenshot.

The integration works in a script but fails in CI

Compare browser versions, viewport settings, timing, cookies, and secret availability between local and CI environments. For a wider testing checklist, see CAPTCHA handling in automated QA.

Responsible Use

Use Queue-it and BotDeflector automation only for systems you own, QA environments you operate, or workflows for which the site owner has granted explicit permission. A CAPTCHA-solving API does not grant access rights or override a site's terms, queue rules, rate limits, or authorization requirements.

Keep test volume bounded, avoid high-demand public events unless they are part of an approved test, and log only the minimum diagnostic data. API keys, cookies, flowToken values, and returned tokens should be treated as secrets and excluded from screenshots, analytics, and long-term logs.

Conclusion

Queue-it CAPTCHA handling now requires a BotDeflector-aware integration. Use AntiBotdeflectorTaskProxyLess for the session token flow and read the result from solution.token; use VisionEngine with the botdeflector module only when the challenge supplies the foreground and background images needed for coordinate recognition.

The key implementation rule is to preserve the original browser context from challenge capture through result submission. For authorized Queue-it testing, CapSolver provides both documented BotDeflector paths through the same task API.

FAQ

Q: What task type should I use for Queue-it BotDeflector token mode?

Use AntiBotdeflectorTaskProxyLess when you have websiteURL, domain, and a current flowToken. Poll getTaskResult and read the completed value from solution.token.

Q: Does Queue-it BotDeflector token mode require a CAPTCHA image?

No. The token-mode task uses the page URL, BotDeflector domain, and flowToken. If the challenge instead exposes a foreground image and background image for visual recognition, use the separate VisionEngine path.

Q: When should I use the VisionEngine botdeflector module?

Use VisionEngine with module: "botdeflector" for the visual recognition step that supplies image and imageBackground. The API returns solution.points directly in the createTask response.

Q: Why can the BotDeflector domain differ from the Queue-it page URL?

BotDeflector defines websiteURL and domain as separate task fields, so the challenge service may use a hostname different from the visible Queue-it page. Capture both values from the active integration.

Q: Can I reuse a returned BotDeflector token in another browser session?

No reuse should be assumed. Apply the token to the same authorized browser flow that produced the challenge inputs; if the page or challenge refreshes, capture new inputs and create a new task.

Q: Is automated Queue-it CAPTCHA handling permitted?

It is appropriate only when you own the system or have explicit authorization to test or automate it. Respect the site's terms, access controls, queue policies, rate limits, and applicable law.