hCaptcha Error Codes Explained

hCaptcha errors fall into three buckets: widget-level errors that the user sees in the browser, solver API errors returned when you submit a task, and validation errors returned by the protected site after you inject a token. This guide covers every common error code, what triggers it, and the exact remediation step.

For background on hCaptcha mechanics, see the hCaptcha Guide. For a working Python implementation, see How to Solve hCaptcha in Python.

Quick lookup table

Widget-level errors (user-visible)

rate-limited

The hCaptcha widget shows "rate-limited" when the same IP / fingerprint has triggered the challenge too many times in a short window. Trigger thresholds depend on the site's enterprise tier but typically activate after ~30–50 challenges per minute from one IP.

Fix: Rotate the source IP via residential proxy and reduce request rate. If you are using a solver, the rate limit is happening on the page-load side, not the solve side — your solver requests are unaffected, but the page will not present a solvable challenge until the rate limit clears (5–15 minutes).

network-error

The widget could not reach hcaptcha.com. Causes:

• DNS / firewall blocking *.hcaptcha.com
• Page blocked the script from running (CSP)
• Headless browser running with --disable-network or similar

Fix: Whitelist hCaptcha domains in your network policy. In Playwright / Puppeteer, ensure you are not blocking hcaptcha.com in any route handler.

# WRONG — blocks hCaptcha
page.route("**/*.{png,jpg,svg}", lambda r: r.abort())

# RIGHT — only block from non-hCaptcha origins
page.route("**/*", lambda r: (
    r.continue_() if "hcaptcha.com" in r.request.url
    else r.continue_() if r.request.resource_type != "image"
    else r.abort()
))

Site-backend validation errors

These come from the protected site after you POST your form with the solved token. The site forwards the token to https://api.hcaptcha.com/siteverify and proxies the JSON response.

invalid-input-response

The token you submitted is no longer valid. Causes:

1. Expired — hCaptcha tokens are valid for ~120 seconds. Solving with a slow provider and then waiting on a slow form submit can blow the window.
2. Wrong site / domain — token was solved against a different pageurl than the site validates.
3. Already used — tokens are single-use. Re-submitting the same token returns invalid.

Fix:

# Solve and submit in the same call path
token = solve_hcaptcha(api_key, page_url, site_key)
response = requests.post(form_url, data={
    **form_fields,
    "h-captcha-response": token,
}, timeout=10)  # don't sit on the token

missing-input-response

The site's verify call did not receive the response parameter. This means your form submission did not include the token field.

Fix: Confirm you are injecting into the textarea named h-captcha-response (not g-recaptcha-response — that is reCAPTCHA). If the form uses a custom field name, find it in the page source.

Solver API errors

These come from your solver provider when you submit the task or poll the result.

ERROR_CAPTCHA_UNSOLVABLE

The solver's worker or ML model attempted but could not solve the challenge within its time budget. Common with:

• Newly deployed hCaptcha Enterprise variants the provider has not trained on
• Sites that send an unusual rqdata payload
• Widgets running in iframes the worker cannot fully load

Fix: Retry once. If the failure rate exceeds 5–10% on a single site, the provider's model may be lagging — switch to a provider with a higher reported success rate (see the best hCaptcha solver ranking).

ERROR_NO_SLOT_AVAILABLE

The provider's worker queue is saturated. Common during peak hours (US business day) on flat-rate-thread providers.

Fix: Backoff + retry. If persistent, increase your subscription's thread / capacity tier or fail over to a secondary provider for spikes.

ERROR_KEY_DOES_NOT_EXIST / ERROR_WRONG_USER_KEY

Authentication problem. Check:

• Key has no leading / trailing whitespace
• Key is the right format (32-char hex for most providers)
• You are calling the right provider's endpoint with the right key

api_key = os.environ["HCAPTCHA_API_KEY"].strip()
assert len(api_key) == 32, f"unexpected key length: {len(api_key)}"

ERROR_ZERO_BALANCE

Out of credit. Top up. For pay-per-solve providers, set a CloudWatch / cron alarm at $5 remaining.

Enterprise-only errors

hCaptcha Enterprise sites may also return:

• bot_detected — your session was flagged before the challenge was even presented. Fix: rotate fingerprint (User-Agent, viewport, WebGL signature). A solved token will not help here.
• invalid_rqdata — the rqdata value embedded in the page must be passed to the solver. See the hCaptcha Python guide for the parameter name.

When to switch providers

If you see one error category dominating (ERROR_CAPTCHA_UNSOLVABLE > 5%, or ERROR_NO_SLOT_AVAILABLE > 1%), the provider is the problem, not your code. The current ranked list of hCaptcha solvers by success rate is on captcharank.com/compare.

FAQ

Why does my token work in dev but fail in production? Different pageurl — hCaptcha binds tokens to the URL submitted with the solve request.

Can I cache hCaptcha tokens? No. Tokens are single-use and expire in ~120 seconds.

Does hCaptcha rate-limit by IP or by fingerprint? Both, with IP being the dominant signal at the free tier and fingerprint added at Enterprise.

Which solver has the lowest hCaptcha error rate? See the hCaptcha solver ranking — ordered by current CaptchaRank benchmark success rate.