Error handling and validation

​

Pre-import validation

After you upload your file and map its columns, Qwoty validates your data before importing it. You can catch and fix errors without touching your existing data.

​

How it works

The import wizard surfaces errors at each step:

​

Error files

Both Download error rows (Confirm step) and Download unimported rows (Result step) return a CSV with your columns plus an erreur column that explains why each row failed. Fix the rows and import that file again: it contains only the failed rows.

​

Common error types

​

Duplicate identifiers

Cause: The same product_id or price id appears twice in the file, or a product_api_name is already used by another product. Fix:

• Remove or merge duplicate rows
• Change the product_api_name, or set product_id to update the existing product instead

See Uniqueness constraints.

​

Invalid format

Cause: A value doesn’t match the expected format: invalid UUID, value outside the allowed list, percentage out of the 0–100 range, text in a number column. Fix: Edit the cell. See Field mapping for the format of each field type. Common offenders:

• settings[recurrence_type] = monthly instead of recurring
• pricing_model = Tiered instead of Graduated Tiered or Volume Tiered
• amount = 1,234.00 (thousands separator)
• percent = 0.2 when you meant 20%

​

Missing required fields

Cause: A required column (settings[recurrence_type] for products, id and pricing_model for prices) is empty on a row, or a Volume or Graduated price has no first tier. Fix: Fill in the value, or remove the row from your file.

​

Record not found

Cause: The referenced record doesn’t exist: a product_id or price id that isn’t in your workspace, a price key whose product, pricebook, or billing frequency doesn’t match, or a variant option that wasn’t created. Fix:

• Create the referenced records first (see Import relations)
• Or correct the reference to match an existing record

​

Inconsistent values

Cause: Rows that belong to the same product carry inconsistent values (for example, a different settings[recurrence_type]). Fix: Use the same values on every row of the same product.

​

Unknown columns

A column that matches no Qwoty field is ignored. Map it manually at the Mapping step if it should be imported.

​

Permission errors

Cause: Your role isn’t allowed to modify a field. Fix: Ask your workspace admin to check your role permissions.

​

Tips for fewer errors

1. Start from the template or an export: it shows the exact column headers and formats
2. Clean your data first: remove blank rows, fix typos, normalize enum values
3. Import in the right order: catalogs and options in the app, then products, then prices
4. Test with a small batch before importing thousands of rows
5. Check for duplicates before uploading: sort your file by the identifier column

​

Related