Error handling and validation

Documentation Index

Fetch the complete documentation index at: https://docs.qwoty.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Pre-import validation

After uploading your file and mapping fields, Qwoty validates your data before importing. This lets you catch and fix errors without affecting your existing data.

​

How it works

The 4-step import wizard surfaces errors at two points:

​

Error display

Errors are surfaced in two ways:

• At the Confirm step — a summary count tells you how many rows have validation errors before you commit
• At the Result step — after import, the Download unimported rows button gives you a CSV listing every failed row, the column at fault, and the validation message

The unimported-rows CSV is the same format as your original file, plus an error_reason column. Fix the rows in your spreadsheet and re-upload — only the failed rows are processed on the second import.

​

Common error types

​

Duplicate values

Cause: A unique field (like product_api_name) already exists in Qwoty or appears twice in your file. Fix:

• Edit the duplicate value in your CSV and re-upload
• Remove one of the duplicate rows
• If you intended to update the existing record, populate the id column (the import detects updates automatically)

See Uniqueness constraints for the full list of unique fields.

​

Invalid format

Cause: A value doesn’t match the expected format — invalid UUID, wrong date format, lowercase enum where Qwoty expects capitalized values, percentage out of range. Fix: Edit the cell to match the expected format. See Field mapping for the format requirements of each field type. Common offenders:

• pricing_model = flat instead of Flat (case-sensitive)
• settings[recurrence_type] = monthly instead of recurring
• default_vat = 20.0 instead of FR_200
• amount = 99,00 instead of 99.00 (wrong decimal separator)
• settings[is_active] = TRUE instead of true (booleans must be lowercase)

​

Missing required fields

Cause: A column marked with * in the Mapping step is empty for a given row. Fix: Enter a value in the required field, or remove the row from your file.

​

Relation not found

Cause: The referenced record doesn’t exist — for example, a parent_product_api_name that points to a master that wasn’t imported, or a pricebook_id referencing a pricebook that doesn’t exist. Fix:

• Import the parent records first (see Import order)
• Or correct the reference value to match an existing record

​

Inconsistent values within a master

Cause: Two variants of the same master declare different settings[recurrence_type], different option names, or different shipping defaults. Fix: Standardize the values across all variants of the same master. A master has a single recurrence type and a single set of option names — variants only differ on option values.

​

Wrong file separator

Cause: Your CSV uses semicolon ; instead of comma , (or vice versa). Qwoty expects comma. Fix: Re-export your file with comma as the separator. In Excel, save as CSV UTF-8 (Comma delimited).

​

Tips for fewer errors

1. Download the example file from the import screen first — it shows the exact column headers and expected formats
2. Clean your data in your spreadsheet first — remove blank rows, fix typos, normalize enum values
3. Import files in the correct order — Master products → Products → Prices
4. Test with small batches before importing thousands of rows — fix the systematic issues, then run the full import
5. Check for duplicates before uploading — sort your file by the unique field
6. Limit your file size — split very large datasets into batches of a few thousand rows each, or use the API

​

Related