Validation Engine

Error Detection

Learn how ImportCheck scans your catalog file, how errors are located, classified and returned — and what happens when the engine encounters edge cases.

How the engine works

File parsing

The engine reads the raw file bytes, detects the encoding (UTF-8, latin-1, Windows-1252) and parses the content into a row/column structure. CSV files go through separator detection first.

Header validation

The first row is compared against the required column set (sku, name, price, vat_rate, stock). Missing headers immediately produce MISSING_HEADER errors. The scan stops here if any required header is absent.

Row-level scan

Every data row is checked against all active rules in parallel. Each violation produces an error object with the row index, column name, error code and a human-readable message.

Cross-row checks

After the per-row pass, cross-row rules run (e.g. duplicate SKU detection, which requires comparing all rows together).

Result assembly

All violations are sorted by row then by column. Counts per severity level (errors, warnings, infos) are computed. The result is returned to the dashboard and written to the downloadable report.

Error object structure

Each detected issue is represented as a JSON object in the API response and as a row in the downloaded Excel report:

{
  "row": 14,
  "column": "price",
  "code": "INVALID_PRICE",
  "severity": "error",
  "value": "-5.00",
  "message": "Price must be a positive number. Got: -5.00"
}

row

1-based row index in the original file (row 1 = header).

column

Name of the column where the violation was found.

code

Machine-readable error code. See Validation Rules for the full list.

severity

"error", "warning" or "info".

value

The raw cell value that caused the violation (as a string).

message

Human-readable description including the problematic value.

Edge cases and behaviour

Completely empty rows

Empty rows (all columns blank) at the end of the file are silently skipped. Empty rows in the middle of the data are flagged with EMPTY_SKU and EMPTY_NAME.

Rows with only whitespace

Rows where every cell contains only spaces or tabs are treated as empty and skipped.

BOM in CSV files

UTF-8 BOM (byte order mark) at the start of a file is stripped before parsing. It will not appear as a character prepended to the first column name.

Very large files

Files above the plan row limit are rejected with FILE_TOO_LARGE before scanning starts. Upgrade to the Pro plan for up to 100,000 rows.

Multiple errors on the same row

All violations for a row are reported. Fixing one error will not hide another on the same row.

Zero errors ≠ import success. ImportCheck validates against the standard column set. Your ERP may have additional constraints (e.g. unique product names, category codes, supplier IDs) that are not checked here. Always test a small batch in a staging ERP environment first.

Accessing results via API

Pro plan users can submit files and retrieve results programmatically:

# Upload a file
POST /api/v1/uploads
Content-Type: multipart/form-data
Authorization: Bearer <token>

# Trigger analysis
POST /api/v1/analyses
{ "upload_id": "<uuid>" }

# Get errors
GET /api/v1/analyses/<id>
→ { "status": "completed", "error_count": 3, "errors": [...] }

← Validation Rules Reports →