CaptchaFox Errors and Troubleshooting (Beta): Fixes by Error Code

CaptchaFox solving is supported in beta on CaptchaAI (rolled out mid-2026 alongside Friendly Captcha and Lemin). Because it is a beta solver, expect to spend a little more time getting the request shape right — and expect that most failures come from four causes: a wrong sitekey, a pageurl that does not match the challenge, a token that expired or was applied incorrectly, and proxy problems. This guide maps each symptom to the standard in.php / res.php error code and gives you the fastest fix.

The single most important thing to know up front: CaptchaFox is a proxy-required task type. You must send your own proxy and proxytype at submission, and you must use the returned user_agent when you send the token back to the target site. Skip either step and the token will look valid but fail on the page.

How CaptchaFox solving works on CaptchaAI (beta)

Before debugging errors, confirm your flow matches the four-step contract from the official CaptchaFox API docs:

1. Extract the sitekey from the live network request. Trigger the challenge, open the browser Network tab, and find the request named challenge. The sitekey is the segment in the request URL between https://api.captchafox.com/captcha/ and /challenge (it starts with sk_).
2. Submit the task to https://ocr.captchaai.com/in.php with method=captchafox, pageurl, sitekey, proxy, and proxytype.
3. Poll for the result at https://ocr.captchaai.com/res.php with action=get and the task id. The response returns both a request (the token) and a user_agent.
4. Submit the token back to the target site using that same user_agent header.

If you are integrating from scratch rather than debugging an existing flow, start with the full walkthrough in How to solve CaptchaFox using API — this guide assumes that flow and focuses on what to do when it fails.

The required submission parameters are fixed. Do not invent extras:

Because this is a beta solver, CaptchaAI does not publish a solve-speed or success-rate figure for CaptchaFox. Do not build alerting around a fixed latency SLA yet — poll patiently and treat CAPCHA_NOT_READY as normal.

The four CaptchaFox-specific failure patterns

1. Wrong sitekey → ERROR_WRONG_CAPTCHA_ID

Symptom: Polling res.php returns ERROR_WRONG_CAPTCHA_ID, or the solve completes but the target page rejects the token.

Cause: The sitekey is invalid or does not match the challenge on the page. The most common mistake is copying the key from cached page source instead of the live network request, or grabbing a key from a different widget.

Fix: Re-extract the sitekey from the live challenge request in the Network tab. Confirm it begins with sk_ and matches the URL segment exactly:

https://api.captchafox.com/captcha/sk_bo3q016TDv4Jey6fibTVChVS9z-cYdCO/challenge
                                    └──────────── sitekey ────────────┘

2. pageurl mismatch → ERROR_PAGEURL / silent rejection

Symptom: ERROR_PAGEURL at submission (the field is missing), or the API returns a token but the target site rejects it (the field is present but wrong).

Cause: CaptchaFox binds the challenge to the page context. If the pageurl you send does not match where the widget actually loaded — wrong path, missing query string, http vs https, or the URL of an embedding page instead of the iframe — the token is solved against the wrong context.

Fix: Send the exact URL where CaptchaFox renders, including protocol, path, and any query parameters. If the widget loads inside an iframe or via an AJAX route, use that route's URL, not the parent page's.

3. Expired or misapplied token → downstream rejection

Symptom: status: 1 with a valid-looking token, but the target site returns a 403 or a "verification failed" response.

Cause: One of three things — the token expired before you submitted it, you did not send the returned user_agent, or you posted it to the wrong field. CaptchaFox tokens are single-use and time-limited; a slow handoff kills them.

Fix: Apply the token immediately after receiving it, in the same session, and always send the user_agent from res.php as your User-Agent header. Post the token to the field the target expects (commonly captchafox_token — confirm against a manual solve's network traffic).

4. Proxy problems → ERROR_BAD_PROXY / ERROR_PROXY_CONNECTION_FAILED

Symptom: Submission fails with ERROR_BAD_PROXY, or polling returns ERROR_PROXY_CONNECTION_FAILED, or the solve fails as ERROR_CAPTCHA_UNSOLVABLE.

Cause: CaptchaFox is proxy-required. A missing, malformed, dead, or geo-blocked proxy means CaptchaAI cannot load the challenge in your context.

Fix: Verify the proxy format (login:password@host:port) and that proxytype matches the actual protocol. Test the proxy independently before submitting, and rotate to a known-good IP. For a deeper walkthrough, see CaptchaAI proxy connection failures.

Request-stage errors (in.php)

These come back when you submit the task.

• ERROR_WRONG_USER_KEY — The key is malformed (it must be 32 characters). Re-copy it from your dashboard with no stray whitespace.
• ERROR_KEY_DOES_NOT_EXIST — The key is well-formed but not active. Confirm the key in your CaptchaAI dashboard.
• ERROR_ZERO_BALANCE — No free threads or insufficient balance. Top up, reduce concurrency, or wait for threads to free up.
• ERROR_PAGEURL — pageurl is missing. Add the full page URL (see failure pattern 2).
• ERROR_BAD_PARAMETERS — A required field is missing or malformed. For CaptchaFox, check that method=captchafox, sitekey, pageurl, proxy, and proxytype are all present.
• ERROR_BAD_PROXY — The submitted proxy is marked bad. Switch to a healthy proxy.

Result-stage errors (res.php)

These come back when you poll for the answer.

• CAPCHA_NOT_READY — Not an error. The solve is still in progress; poll again every ~5 seconds.
• ERROR_WRONG_ID_FORMAT — The task ID must be numeric. Use the exact id returned by in.php.
• ERROR_WRONG_CAPTCHA_ID — The ID does not match a submitted task, or the sitekey was wrong. Verify you are polling the ID from your submission response.
• ERROR_PROXY_CONNECTION_FAILED — CaptchaAI could not load the challenge through your proxy. Switch to a healthy proxy.
• ERROR_CAPTCHA_UNSOLVABLE — The challenge could not be solved after several attempts. Re-extract a fresh sitekey, confirm the pageurl, verify the proxy, then resubmit.
• ERROR_INTERNAL_SERVER_ERROR — Transient server-side issue. Retry after ~10 seconds with exponential backoff.

Quick error-to-fix reference

Python: CaptchaFox solve with error handling (beta)

import time
import requests

API_KEY = "YOUR_API_KEY"
SUBMIT_URL = "https://ocr.captchaai.com/in.php"
RESULT_URL = "https://ocr.captchaai.com/res.php"


def solve_captchafox(sitekey, pageurl, proxy, proxytype="HTTP"):
    """Submit a CaptchaFox (beta) task and return token + user_agent."""
    submit = requests.post(
        SUBMIT_URL,
        data={
            "key": API_KEY,
            "method": "captchafox",
            "pageurl": pageurl,
            "sitekey": sitekey,
            "proxy": proxy,
            "proxytype": proxytype,
            "json": 1,
        },
        timeout=30,
    ).json()

    if submit.get("status") != 1:
        raise RuntimeError(f"Submit failed: {submit.get('request')}")

    task_id = submit["request"]
    print(f"Task created — id: {task_id}")
    time.sleep(15)

    for _ in range(60):
        result = requests.get(
            RESULT_URL,
            params={"key": API_KEY, "action": "get", "id": task_id, "json": 1},
            timeout=30,
        ).json()

        if result.get("request") == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue

        if result.get("status") == 1:
            # Use this user_agent when you submit the token back to the site
            return result["request"], result.get("user_agent")

        raise RuntimeError(f"Solve error: {result.get('request')}")

    raise TimeoutError("CaptchaFox solve timed out")


token, user_agent = solve_captchafox(
    sitekey="sk_bo3q016TDv4Jey6fibTVChVS9z-cYdCO",
    pageurl="https://example.com/login",
    proxy="user:password@111.111.111.111:8080",
)
print(f"Token: {token}")
print(f"User-Agent: {user_agent}")
# Submit token to the site with header User-Agent: <user_agent>

Node.js: CaptchaFox solve with error handling (beta)

const API_KEY = "YOUR_API_KEY";
const SUBMIT_URL = "https://ocr.captchaai.com/in.php";
const RESULT_URL = "https://ocr.captchaai.com/res.php";

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function solveCaptchaFox(sitekey, pageurl, proxy, proxytype = "HTTP") {
  const submitResp = await fetch(SUBMIT_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      key: API_KEY,
      method: "captchafox",
      pageurl,
      sitekey,
      proxy,
      proxytype,
      json: "1",
    }),
    signal: AbortSignal.timeout(30_000),
  });

  const submit = await submitResp.json();
  if (submit.status !== 1) {
    throw new Error(`Submit failed: ${submit.request}`);
  }

  const taskId = submit.request;
  console.log(`Task created — id: ${taskId}`);
  await sleep(15_000);

  for (let i = 0; i < 60; i++) {
    const resultResp = await fetch(
      `${RESULT_URL}?${new URLSearchParams({
        key: API_KEY,
        action: "get",
        id: taskId,
        json: "1",
      })}`,
      { signal: AbortSignal.timeout(30_000) }
    );
    const result = await resultResp.json();

    if (result.request === "CAPCHA_NOT_READY") {
      await sleep(5_000);
      continue;
    }
    if (result.status === 1) {
      // Reuse result.user_agent when submitting the token to the site
      return { token: result.request, userAgent: result.user_agent };
    }
    throw new Error(`Solve error: ${result.request}`);
  }
  throw new Error("CaptchaFox solve timed out");
}

(async () => {
  const { token, userAgent } = await solveCaptchaFox(
    "sk_bo3q016TDv4Jey6fibTVChVS9z-cYdCO",
    "https://example.com/login",
    "user:password@111.111.111.111:8080"
  );
  console.log("Token:", token);
  console.log("User-Agent:", userAgent);
})();

FAQ

Why does my CaptchaFox token get rejected even though status is 1?

The API solved the challenge, but the token failed downstream for one of three reasons: it expired before you submitted it, you did not send the user_agent returned by res.php, or you posted it to the wrong field. Apply the token immediately, in the same session, with the returned User-Agent header. The same pattern applies to other token CAPTCHAs — see Turnstile token invalid after solving.

Where do I find the correct CaptchaFox sitekey?

Trigger the challenge, open the browser Network tab, and find the request named challenge. The sitekey is the sk_... segment in the request URL between https://api.captchafox.com/captcha/ and /challenge. Always read it from the live request, not cached page source — a stale or wrong key produces ERROR_WRONG_CAPTCHA_ID.

Do I really need a proxy for CaptchaFox?

Yes. CaptchaFox is a proxy-required task type on CaptchaAI. You must send proxy and proxytype at submission, and the proxy must be healthy — a bad or unreachable proxy causes ERROR_BAD_PROXY, ERROR_PROXY_CONNECTION_FAILED, or ERROR_CAPTCHA_UNSOLVABLE. If proxy errors dominate your logs, work through CaptchaAI proxy connection failures.

Is CaptchaFox fully supported on CaptchaAI?

CaptchaFox is supported in beta. The solve flow, endpoints, and error codes match the standard in.php / res.php pattern, but there is no published solve-speed or success-rate figure yet, so avoid hard-coding a latency SLA. Friendly Captcha and Lemin are also in beta; if you are comparing beta solvers, see How Friendly Captcha works and how to handle it.

What does CAPCHA_NOT_READY mean for CaptchaFox?

It is not an error — the solve is still in progress. Poll res.php again every ~5 seconds until you get status: 1 or a terminal error. Only treat repeated ERROR_CAPTCHA_UNSOLVABLE responses as a real failure, and when you do, refresh the sitekey, page URL, and proxy before resubmitting. The complete submit-and-poll pattern is covered step by step in How to solve CaptchaFox using API.

Fix your CaptchaFox workflow

If your CaptchaFox integration is failing, work through it in this order:

1. Sitekey — Re-extract the sk_... value from the live challenge request.
2. Page URL — Send the exact URL where the widget loads, protocol and path included.
3. Proxy — Confirm proxy and proxytype are present and the IP is healthy.
4. Token handoff — Apply the token immediately with the returned user_agent.

Once those four are correct, the standard in.php / res.php error codes tell you exactly what to fix next. Start solving CaptchaFox (beta) with CaptchaAI and confirm each parameter against the CaptchaFox API docs before you resubmit.