How to Add CAPTCHA Error Handling to n8n with CapSolver

An importable n8n error-handling workflow with bounded result polling, normalized states, and explicit stop paths.

English · 简体中文 · 日本語 · Español · Português · 한국어

Introduction

Developers using n8n can encounter CAPTCHA during a permitted browser or workflow step, causing the automation to stop or return the wrong state. This repository shows how to connect n8n with CapSolver, recognize the challenge, request a solution through an isolated adapter, and resume once with clear stop conditions. It focuses only on the n8n integration pattern and does not bind the example to a particular business scenario.

Content type: Agent integration. Primary keyword: n8n CAPTCHA solving workflow tutorial (keyword-library row 70).

Problem

N8n workflows need a visible error branch when a permitted automation step returns a captcha challenge instead of ordinary task data. The implementation returns explicit challenge_detected, ready, or stopped states instead of silently guessing.

Features

• Mock-first and deterministic local demonstration
• Allowlisted hosts and one bounded resume attempt
• CapSolver API isolated behind a small adapter
• Redacted output with structured stop reasons
• Unit tests and CI-ready project layout

How It Works

1. Validate that the target host is explicitly allowlisted.
2. Classify the browser or workflow observation.
3. Send only the authorized CAPTCHA task through the adapter.
4. Poll with a fixed attempt budget and stop conditions.
5. Resume once and emit a minimal normalized result.

The adapter follows the official createTask API concept and getTaskResult API concept.

Quick Start

python -m unittest discover -s tests -v
PYTHONPATH=src python examples/mock_workflow.py

n8n Workflow

Import examples/n8n-workflow.json into n8n. Configure CAPSOLVER_API_KEY in the n8n environment, then pass only tasks for owned, mock, or explicitly authorized targets. The workflow uses a manual trigger, challenge check, createTask, bounded getTaskResult polling, and a normalized final state.

Project Structure

src/captcha_workflow/  bounded workflow and adapter
examples/              offline demonstration/n8n-workflow.json
tests/                 behavior and policy checks
docs/                  five localized README files
assets/                shared English cover

Testing

Tests verify the successful mock path, allowlist rejection, and bounded challenge handling. No live key or production target is required.

Responsible Use

Use only public data, owned systems, or targets for which you have explicit authorization. Respect terms, rate limits, purpose limitation, field minimization, retention limits, and stop conditions. Do not use this example for private or restricted data, credential access, detection evasion, or unbounded collection. Travel, pricing, inventory, personal, financial, employment, or contact data requires a documented lawful purpose and proportionate human review.

Conclusion

This repository provides an importable n8n error-handling workflow with bounded result polling, normalized states, and explicit stop paths. Developer sharing CapSolver integration examples. The final product reference is CapSolver.

License

MIT