What to do when a run gets blocked

The two kinds of wall

A CHALLENGE wall presents something interactive — a CAPTCHA widget, a managed-challenge interstitial. It is potentially clearable in session, so a retry on a better browser profile can legitimately work. A SCORE wall assigns an invisible reputation score and refuses low ones with nothing to solve. No fingerprint, proxy or retry reliably moves a score; a real person's session does.

• Score walls: reCAPTCHA Enterprise and v3, DataDome, PerimeterX / HUMAN, Kasada, Akamai Bot Manager, Imperva / Incapsula.
• Challenge walls: Cloudflare interstitials, reCAPTCHA v2, hCaptcha, Arkose, generic CAPTCHA widgets.
• A challenge that PERSISTED after an attempt is treated like a score wall — the automated path is exhausted for that run.

Read the response before you retry

A blocked run names the vendor and, when the wall is one automation cannot reliably pass, returns code: "connect_required" with a READY one-time connectUrl already minted. That is not a failure message, it is an instruction: hand the link to a human. On hosts with repeated score-wall blocks, a run may short-circuit to that response WITHOUT executing at all, refunding the reserve — that is the policy engine saving you the cost of a run that was going to fail.

{
  "code": "connect_required",
  "connectUrl": "https://twin-browser.com/connect/…",
  "connectId": "…",
  "connectExpiresAt": "2026-09-02T10:44:00.000Z",
  "policy": { "fastpath": "score-wall" }
}

Before you reach for stealth: fix the cheap things

Several blocks are self-inflicted and cost nothing to fix. An exit IP in one country with a browser announcing a different language and timezone is a mismatch a site can trivially see — set one `country` and let the locale and timezone derive from it. Rotation on an account-bound run destroys the identity you were protecting; use a stable `account` label instead. And `blockAds` is off by default because on a guarded target the absence of the usual third-party requests is itself unusual.

# One country drives BOTH the residential exit and the browser identity
#   "country": "de"                      → locale + timezone derived
#   "proxyType": "residential" | "mobile"  → mobile = highest-reputation exit
#   "account": "acme-ops"                → sticky egress for this identity
#
# Do NOT also set "proxyRotate": true on an account-bound run —
# rotation and stickiness are opposites.

When stealth is the right call — and when it is not

Stealth routes the run to a full desktop browser profile: real Chrome, human-calibrated timing, residential egress. It requires a Pro or Enterprise plan and an explicit authorized: true attestation, both checked BEFORE any credit is reserved, so a refused stealth request is free. It bills the run price plus a surcharge on SUCCESS. Use it as a retry after a challenge the standard fleet could not clear — not as a default posture, where it adds cost without adding capability.

curl -X POST https://twin-browser.com/api/v1/run \
  -H "Authorization: Bearer $TWIN_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://guarded.example.com/dashboard",
    "prompt": "open the account page and export the statement",
    "success": { "kind": "extracted" },
    "stealth": true,
    "authorized": true
  }'

# 400 — "authorized" missing; the attestation is required, never inferred
# 403 — { "code": "plan_required" }; Pro or Enterprise only
# 501 — no stealth fleet configured; it fails CLOSED rather than running
#       honestly and billing you at the premium rate

The answer to a score wall is a person

Mint a connect link — or use the one the blocked run already handed you. The account owner signs in by hand in a hosted browser, the session is captured, and every later run on that host restores it. This is not a workaround; a real sign-in carries the reputation the score demanded, which is exactly what no client-side lever can synthesise.

And if you are being paced by your own governor

A 429 whose body carries a `reason` of cooldown, min_gap or window is not the target — it is the cadence governor protecting your account from the target. It costs nothing (the check runs before the credit reserve) and it tells you what to change: "min_gap" means space the runs out, "window" means you are doing too much on one identity per hour, "cooldown" means the site already pushed back and the account is resting. Honour the Retry-After; retrying immediately defeats the point.