GuidesOneMux

Build a Repeatable n8n Data Extraction Workflow with Validation, Retries, and Human Review

Design an n8n extraction workflow that validates structured output, retries transient failures, routes uncertain records for review, and can be evaluated against fixed test cases.

AI

Summary · TL;DR

Separate extraction from validation and side effects in n8n. Validate every result against an explicit contract, retry only recoverable failures within a fixed limit, and send uncertain or consequential records to a human before they are committed.

Key Takeaways

  • Treat the extraction result as untrusted input until it passes schema and business-rule checks.
  • Set a retry limit and distinguish transient errors from invalid model output.
  • Use human review for ambiguous records or consequential actions; show reviewers the exact proposed values.
  • Keep a fixed test set with expected outputs and explicit pass criteria so changes can be compared consistently.
On this page (7)

An n8n extraction workflow is easier to trust when it has three separate gates: schema validation, bounded recovery, and human review. Do not let an AI-generated response flow directly into a database update or external message. First check that it has the expected shape, then decide whether it is safe to process automatically.

This design is illustrative, not a tested workflow export. Node labels and available options can differ by n8n version. The official n8n guide documents human approval for selected tools connected to an AI Agent; it does not describe a general-purpose approval step for every extracted record. n8n: Human-in-the-loop for tools.

Start with a narrow extraction contract

Choose one record type and define exactly what downstream nodes need. For example, extracting invoice fields might produce:

{
  "invoice_number": "INV-1042",
  "invoice_date": "2025-02-14",
  "total": 128.50,
  "currency": "USD"
}

Decide whether each field is required, which types are allowed, and how missing or uncertain values should be represented. Avoid a vague field such as notes as a substitute for a reliable contract. For this example, the rules could be:

  • invoice_number: non-empty string.
  • invoice_date: valid ISO date (YYYY-MM-DD).
  • total: finite number greater than or equal to zero.
  • currency: three uppercase letters.
  • Unknown values: use null only if the contract permits it; never guess.

These are example business rules, not requirements imposed by n8n. Set rules that match your own source documents and destination system.

Build the workflow in separate stages

A practical workflow can follow this sequence:

  1. Trigger and fetch: Receive a document or record and retain its source identifier.
  2. Extract: Ask the chosen extraction step for only the fields in the contract. Require structured output if the selected node or model supports it, but still validate the result yourself.
  3. Parse and validate: Check that the response is parseable and that every field meets its type and business rules.
  4. Branch: Send valid, low-risk records onward. Route invalid or ambiguous records to a review path. Handle transient service errors separately.
  5. Commit: Write to the destination only after validation and, where required, human approval.
  6. Record the outcome: Store the source identifier, extracted result, validation errors, attempt count, and final decision. Avoid logging sensitive document content unless your retention policy allows it.

A validation Code node can implement basic checks after parsing. Adapt the input property and null policy to your preceding nodes:

const item = $input.first().json;
const data = item.extraction; // Set this to the parsed extraction object.
const errors = [];

if (!data || typeof data !== 'object' || Array.isArray(data)) {
  errors.push('Extraction must be a JSON object');
} else {
  if (typeof data.invoice_number !== 'string' || !data.invoice_number.trim()) {
    errors.push('invoice_number must be a non-empty string');
  }

  if (typeof data.invoice_date !== 'string' ||
      !/^\d{4}-\d{2}-\d{2}$/.test(data.invoice_date) ||
      Number.isNaN(Date.parse(`${data.invoice_date}T00:00:00Z`))) {
    errors.push('invoice_date must be a valid YYYY-MM-DD date');
  }

  if (typeof data.total !== 'number' || !Number.isFinite(data.total) || data.total < 0) {
    errors.push('total must be a finite, non-negative number');
  }

  if (typeof data.currency !== 'string' || !/^[A-Z]{3}$/.test(data.currency)) {
    errors.push('currency must be three uppercase letters');
  }
}

return [{ json: { ...item, valid: errors.length === 0, validation_errors: errors } }];

This checks shape and simple constraints, not whether the invoice value is factually correct. A well-formed but misread amount still needs a source comparison, confidence policy, or human check.

Retry the right failures—and stop

Set a small, explicit retry limit for failures likely to be temporary, such as a rate limit or a transient connection error. Use the node's retry settings where available, or create a controlled loop with an attempt counter and a delay. Confirm how your n8n version handles errors and retries before relying on a particular setting.

Do not blindly retry a schema failure as if it were a network problem. A bounded correction attempt may be useful—for example, ask the extraction step to return the same fields as valid JSON—but count it against a separate, visible limit. If the response remains invalid, route it for review or mark it failed. Never allow an unbounded loop.

Keep separate outcomes such as retryable_error, invalid_output, and needs_review. This makes workflow runs easier to diagnose and prevents an invalid record from being mistaken for a successful extraction.

Put people at the right decision point

For record review, send a reviewer the source reference, proposed values, validation warnings, and a clear approve/edit/reject choice. Ensure the workflow waits for a decision before writing the record, and define what happens on timeout or rejection. The specific wait-and-resume design depends on the review channel and n8n nodes you use.

n8n's documented AI Agent human-review feature works differently: selected tools can require approval before the agent executes them. The workflow pauses, and the reviewer can approve or deny the proposed tool call; the reviewer sees the tool and its parameters. The guide lists channels including Slack, Telegram, and n8n Chat, and notes that $tool.name and $tool.parameters can be used to provide context. Configure the system prompt to explain what denial means and how the agent should respond. Use this feature when the agent is about to perform an action such as modifying a record—not as a substitute for validating extracted fields. See the official setup guide.

Make evaluation repeatable with fixed cases

Create a small fixture set that includes ordinary, malformed, and ambiguous inputs. For each case, record the expected fields, expected validation result, and whether a human should review it. Run the same cases whenever you change the prompt, schema, parsing logic, or model configuration.

Test caseExpected resultPass condition
Clear invoice with all fieldsValid extractionAll required fields match the fixture and validation passes
Missing invoice dateInvalid or explicitly permitted nullNo invented date; the configured policy is followed
Total contains text instead of a numberInvalid outputRecord does not reach the write step
Two plausible totals on the pageHuman reviewNo automatic commit while the ambiguity remains
Temporary request failureBounded retryAttempts stop at the configured limit; failure is recorded
Reviewer denies a proposed updateNo writeThe rejection is recorded and the workflow follows its denial path

Define limits before running tests: maximum attempts, fields allowed to be null, which errors require review, and which conditions block a write. Report exact-match results by field and count invalid, reviewed, rejected, and failed cases. A small fixture set is a regression check, not proof that extraction will work on every document type.

Troubleshooting checklist

  • Valid JSON still fails: Check whether the parser returns an object or a JSON string, and ensure validation reads the right property.
  • Bad values pass: Add business rules and source-grounded checks; JSON types alone cannot establish factual accuracy.
  • Retries repeat the same failure: Separate transient errors from deterministic schema errors and cap attempts.
  • Reviewers cannot decide: Include the source reference and all proposed values, and make the available decisions explicit.
  • A denied action runs anyway: Put the write behind the approval result, and test denial as a separate fixture.
  • Results change between runs: Keep inputs, prompt, schema, and evaluation criteria fixed; record relevant workflow configuration changes.

Conclusion

In n8n, reliability comes from controlling what happens after extraction: validate against a narrow contract, retry only within a fixed budget, and require human judgment where the record is ambiguous or the action matters. A fixed test set makes those controls observable and repeatable.

FAQ

Does n8n's AI Agent human-review feature validate extracted data?

No. The documented feature pauses selected AI Agent tool calls for approval or denial. Validate extracted fields separately before they are stored or acted on.

Should invalid model output be retried?

Not as a transient error. You may allow a bounded correction attempt, but keep it separate from retries for temporary service failures and route persistent invalid output to review or failure handling.

What should an extraction evaluation test?

Use fixed examples covering valid records, missing or malformed fields, ambiguous source values, retryable errors, and reviewer rejection. Define expected results and pass conditions before running them.

Can an extraction workflow write directly after a valid schema check?

Only if schema validity is sufficient for the use case. A result can have the right types and still be factually wrong, so consequential or ambiguous records may need source checks or human review.

Related articles