Debug reCAPTCHA v3 pageAction mismatches

A reCAPTCHA v3 pageAction mismatch is a practical cause to investigate when an authorized integration receives a token that the destination rejects. CapBypass documents pageAction as an optional field for ReCaptchaV3TaskProxyLess. When the page calls grecaptcha.execute with an action, send that same action in the task. Do not guess an action from a button label or URL path.

This tutorial uses the documented proxyless standard v3 task. It creates a task at https://api.capbypass.pro/createTask, polls https://api.capbypass.pro/getTaskResult, and returns solution.gRecaptchaResponse. Use it only for sites and flows you are authorized to automate.

Identify the action before creating a task

First, inspect the authorized page implementation or its browser network activity. Look for the action passed to grecaptcha.execute, such as login, signup, or submit. That string is the value for pageAction. If the page does not use an action, omit pageAction rather than inventing one.

The documented task requires websiteURL and websiteKey. The websiteURL must be the page serving the challenge, and websiteKey must be the reCAPTCHA site key from that page. For a standard v3 page that uses an action, the task body has this shape:

{
  "type": "ReCaptchaV3TaskProxyLess",
  "websiteURL": "https://example.com/login",
  "websiteKey": "6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696",
  "pageAction": "login"
}

Keep the action, URL, and site key associated with the same authorized page. A token created for one page context should not be treated as a reusable credential for another flow.

Create and poll with curl

Set your CapBypass API key once in the shell, then create the task. Replace only YOUR_API_KEY. The example values for the page URL, site key, and action are the current documentation example values.

export CAPBYPASS_API_KEY=YOUR_API_KEY

CREATE_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST https://api.capbypass.pro/createTask \
  --header 'Content-Type: application/json' \
  --data "{\"clientKey\":\"$CAPBYPASS_API_KEY\",\"task\":{\"type\":\"ReCaptchaV3TaskProxyLess\",\"websiteURL\":\"https://example.com/login\",\"websiteKey\":\"6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696\",\"pageAction\":\"login\"}}")
TASK_ID=$(printf '%s' "$CREATE_RESPONSE" | python3 -c 'import json,sys; print(json.load(sys.stdin)["taskId"])')

while :; do
  RESULT=$(curl --silent --show-error --fail-with-body \
    --request POST https://api.capbypass.pro/getTaskResult \
    --header 'Content-Type: application/json' \
    --data "{\"clientKey\":\"$CAPBYPASS_API_KEY\",\"taskId\":\"$TASK_ID\"}")
  STATUS=$(printf '%s' "$RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("status", ""))')
  [ "$STATUS" = ready ] && break
  sleep 1
done

printf '%s\n' "$RESULT"

The final JSON contains the documented solution.gRecaptchaResponse when the task is ready. Pass that token only to the authorized form or API flow that produced the page context.

Use the same flow in Python

This Python example uses requests. It validates the API error indicator and waits for the documented ready status. Set CAPBYPASS_API_KEY in the environment before running it.

import os
import time
import requests

API_KEY = os.environ["CAPBYPASS_API_KEY"]
BASE_URL = "https://api.capbypass.pro"

payload = {
    "clientKey": API_KEY,
    "task": {
        "type": "ReCaptchaV3TaskProxyLess",
        "websiteURL": "https://example.com/login",
        "websiteKey": "6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696",
        "pageAction": "login",
    },
}
create = requests.post(f"{BASE_URL}/createTask", json=payload, timeout=30)
create.raise_for_status()
create_data = create.json()
if create_data.get("errorId"):
    raise RuntimeError(create_data.get("errorDescription", "createTask failed"))

task_id = create_data["taskId"]
while True:
    result = requests.post(
        f"{BASE_URL}/getTaskResult",
        json={"clientKey": API_KEY, "taskId": task_id},
        timeout=30,
    )
    result.raise_for_status()
    data = result.json()
    if data.get("errorId"):
        raise RuntimeError(data.get("errorDescription", "getTaskResult failed"))
    if data.get("status") == "ready":
        print(data["solution"]["gRecaptchaResponse"])
        break
    time.sleep(1)

If the integration still fails, log the exact action observed on the page and the action sent to createTask, without logging tokens or API keys. Compare the strings exactly, including case. Then verify that the site key and page URL came from the same page.

Use the same flow in TypeScript

Node.js 18 or later provides fetch globally. This complete TypeScript example reads the key from the environment and prints only the ready token.

const apiKey = process.env.CAPBYPASS_API_KEY;
if (!apiKey) throw new Error("CAPBYPASS_API_KEY is required");

const baseUrl = "https://api.capbypass.pro";
const createResponse = await fetch(`${baseUrl}/createTask`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: apiKey,
    task: {
      type: "ReCaptchaV3TaskProxyLess",
      websiteURL: "https://example.com/login",
      websiteKey: "6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696",
      pageAction: "login",
    },
  }),
});
if (!createResponse.ok) throw new Error(`createTask HTTP ${createResponse.status}`);
const createData = await createResponse.json();
if (createData.errorId) throw new Error(createData.errorDescription || "createTask failed");

while (true) {
  const resultResponse = await fetch(`${baseUrl}/getTaskResult`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: apiKey, taskId: createData.taskId }),
  });
  if (!resultResponse.ok) throw new Error(`getTaskResult HTTP ${resultResponse.status}`);
  const resultData = await resultResponse.json();
  if (resultData.errorId) throw new Error(resultData.errorDescription || "getTaskResult failed");
  if (resultData.status === "ready") {
    console.log(resultData.solution.gRecaptchaResponse);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 1000));
}

Check the common mismatch cases

An action can be optional in the API yet mandatory for a particular page flow. If the page invokes grecaptcha.execute with login, submit login. If the page has no action, omit the field. Do not switch to an Enterprise task because of a failed standard v3 attempt: the CapBypass documentation identifies separate Enterprise task types for Enterprise-protected sites.

Also separate a pageAction mismatch from an incomplete task. A missing or incorrect websiteURL or websiteKey changes the task context. A stale token is another operational issue. Create the token when the authorized flow is ready to use it, and avoid placing token values in application logs.

---

Bonus: +5% credits on every top-up

New to CapBypass? Apply code WELCOME_2026 at checkout for an extra 5% in credits on every top-up, with no minimum and no expiry. Redeem it on the top-up page.

---

Verify your fix

For an authorized test page, capture the site key, full page URL, and action from the same page load. Run one task with those values, then submit the returned token through the intended flow. Record whether the action was present and which value you used, but never record the token itself. This makes a mismatch reproducible without exposing credentials.

The documented ReCaptchaV3TaskProxyLess schema is small: websiteURL and websiteKey are required, while pageAction is optional. Treat optional as context-dependent, not as a field to fill with a default. Matching the page action is the direct, testable correction when an authorized reCAPTCHA v3 flow expects one.

Handle task states without hiding errors

Keep task creation, polling, and token submission as separate application steps. A successful HTTP response is not itself a ready token. Read errorId after each API response, then check status. Continue polling only while the task is not ready and no API error has been returned. Put a timeout around the complete operation in production so an upstream incident does not keep a worker open indefinitely.

For a debugging record, retain the task ID, the page URL, the site key identifier, the observed action, and the requested action. Redact API keys and every token value. These fields make it possible to tell a context mismatch from a transport failure without turning operational logs into a credential store. If the page changes from standard v3 to Enterprise, use the documented Enterprise task type rather than reusing the standard v3 configuration.

For the current field definitions and response shape, consult the CapBypass reCAPTCHA v3 documentation. The API reference documents the shared request conventions. Recheck both sources before changing a production integration.