Solve captchas from Node.js with one function

Step 1

Add the helper

Save this file next to your code. It wraps the whole task lifecycle in one function, solve(type, params), so the rest of your project never deals with polling.

• createTask: sends your key, the task type and its fields.
• Fast path: if the answer is already ready, it returns at once.
• Polling: otherwise it checks /getTaskResult/{taskId} every two seconds until the result is ready or your timeout runs out.
• Errors: any errorId: 1 becomes a BypassError carrying the errorCode, so you can branch on it.
• taskId: added to the returned solution, so you can report a wrong answer later.

const API_URL = "https://bypass.so";
const CLIENT_KEY = process.env.BYPASS_API_KEY ?? "";

export class BypassError extends Error {
  constructor(code, description = "", taskId = null) {
    super(`${code}: ${description}`);
    this.name = "BypassError";
    this.code = code;
    this.taskId = taskId;
  }
}

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

async function call(path, init = {}) {
  const res = await fetch(API_URL + path, { ...init, signal: AbortSignal.timeout(30_000) });
  let data;
  try {
    data = await res.json();
  } catch {
    throw new BypassError("HTTP_ERROR", `HTTP ${res.status} without a JSON body`);
  }
  if (data.errorId) {
    throw new BypassError(data.errorCode ?? "ERROR_UNKNOWN", data.errorDescription ?? "", data.taskId);
  }
  return data;
}

export async function solve(type, params, { timeoutMs = 120_000, pollMs = 2_000 } = {}) {
  if (!CLIENT_KEY) {
    throw new BypassError("ERROR_KEY_INVALID", "set the BYPASS_API_KEY environment variable");
  }
  let data = await call("/createTask", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: CLIENT_KEY, type, ...params }),
  });
  const taskId = data.taskId;
  const deadline = Date.now() + timeoutMs;
  while (data.status !== "ready") {
    if (Date.now() > deadline) {
      throw new BypassError("CLIENT_TIMEOUT", `task ${taskId} was not ready after ${timeoutMs / 1000}s`, taskId);
    }
    await sleep(pollMs);
    data = await call(`/getTaskResult/${taskId}?clientKey=${encodeURIComponent(CLIENT_KEY)}`);
  }
  return { ...data.solution, taskId };
}

export const tokenOf = (solution) => solution.gRecaptchaResponse ?? solution.token ?? solution.text;

export const balance = () =>
  call("/balance", { headers: { Authorization: `Bearer ${CLIENT_KEY}` } });

export const reportBad = (taskId) =>
  call(`/reportBad?task_id=${encodeURIComponent(taskId)}`, {
    method: "POST",
    headers: { Authorization: `Bearer ${CLIENT_KEY}` },
  });

Step 2

Solve any supported type

Every task type uses the same call. Only the type name and its fields change. Pick a tab to see a complete, runnable file. Tabs marked soon are ready for launch day, but those types are not live yet. Run it with node solve-image-to-text.mjs (rename to match the tab).

import { solve } from "./bypass.mjs";

const { text } = await solve("MathCaptchaTask", { captchaText: "12 + 30 = ?" });
console.log(text);

Step 3

Handle errors and retries

Some failures are worth a second try and some are not. A missing balance or a wrong key will fail again, so stop and fix it. An unsolvable task or a network hiccup is worth one or two more attempts with a short pause.

import { BypassError, reportBad, solve } from "./bypass.mjs";

const RETRYABLE = new Set(["ERROR_CAPTCHA_UNSOLVABLE", "ERROR_INTERNAL", "HTTP_ERROR", "CLIENT_TIMEOUT"]);

export async function solveWithRetry(type, params, attempts = 3) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await solve(type, params);
    } catch (err) {
      const retryable = err instanceof BypassError ? RETRYABLE.has(err.code) : err.name === "TimeoutError" || err.name === "TypeError"; // fetch rejects with TypeError on network failures
      if (!retryable || attempt >= attempts) throw err;
      console.warn(`attempt ${attempt} failed (${err.code ?? err.name}), retrying`);
      await new Promise((r) => setTimeout(r, 2_000 * attempt));
    }
  }
}

const solution = await solveWithRetry("MathCaptchaTask", { captchaText: "12 + 30 = ?" });
console.log(solution.text);

Step 4

Check your balance and flag wrong answers

GET /balance and POST /reportBad use your key as a Bearer token. Report a task only when the target site actually rejected its answer. The refund is applied once per task, and the task is closed afterwards.

import { balance, reportBad } from "./bypass.mjs";

export async function flagWrongAnswer(solution) {
  const { refunded, balanceUsd } = await reportBad(solution.taskId);
  console.log("refunded units:", refunded, "balance now:", balanceUsd);
}

const { balanceUsd } = await balance();
console.log(`balance: $${balanceUsd.toFixed(2)}`);

Scale

Solve many tasks in parallel

Each task is independent, so throughput grows with concurrency. A small pool of concurrent lanes keeps a fixed number of tasks in flight without any extra package. Start with a limit of 8 and adjust while you watch error rates and spend.

import { readdir, readFile } from "node:fs/promises";
import { solve } from "./bypass.mjs";

async function mapLimit(items, limit, fn) {
  const results = new Array(items.length);
  let next = 0;
  const lanes = Array.from({ length: limit }, async () => {
    while (next < items.length) {
      const i = next++;
      results[i] = await fn(items[i]).catch((err) => ({ error: err.message }));
    }
  });
  await Promise.all(lanes);
  return results;
}

const files = (await readdir("captchas")).filter((f) => f.endsWith(".png"));
const results = await mapLimit(files, 8, async (name) => {
  const imageBase64 = (await readFile(`captchas/${name}`)).toString("base64");
  const { text } = await solve("ImageToTextTask", { imageBase64 });
  return { name, text };
});
console.table(results);

Reference

Task type reference

What each type expects and returns. Prices are per 1,000 solved tasks; larger top-ups add bonus credit (see pricing).

Errors

Troubleshooting

Every error body has the same shape: {"errorId":1,"errorCode":"…","errorDescription":"…"}. Full list in the API reference.

Production

Best practices

• Keep the key out of code

  Read it from an environment variable or your secret store. Never commit it or ship it to a web page.

• Solve right before submit

  Tokens are short-lived. Fill the form first, then request the token and submit at once.

• Cap your concurrency

  Start with 5–10 parallel tasks and raise it while you watch error rates and spend.

• Log every taskId

  It is the only thing you need to debug a result or report a wrong answer.

• Match the page exactly

  Send the URL where the widget renders and the sitekey from that page, not from a different form.

• Report wrong answers

  If a site rejects a solved result, call reportBad with its taskId. The price returns to your balance once.

FAQ

Questions

Policy

Responsible use

Keep going

Next steps

• API referenceEvery endpoint, field and error code
• PricingPer-task prices and top-up bonuses
• PyPython guideScripts, backends and data jobs
• GoGo guideServices and workers on the standard library
• PHPPHP guideWeb apps, cron jobs and CLI scripts
• JvJava guideJVM backends on Java 17+, no libraries
• C#C# / .NET guideAsync .NET 8 services and tools
• RbRuby guideScripts, Rails apps and background jobs
• SeSelenium guideQA suites and WebDriver flows
• PwPlaywright guideEnd-to-end tests in Node.js or Python
• PpPuppeteer guideChrome automation scripts
• ScScrapy guideCrawls that run into captcha pages