Skip to content

Validation Error Codes

Applies to: e-Invoice · e-Way Bill · Which modules do I have?

Purpose

Interpret a validation failure and fix it. These are Complifly's own checks, run before any government call, so they cost nothing and name the exact field at fault.

Audience

Tax operations, support teams, integration developers.

Prerequisites

Reference

The error shape

Every validation error has five fields:

Field Meaning
Level HEADER or ITEM
InvoiceNo The document number
Field The canonical field name, as the government names it — for example BillTo_Pos
Message Human-readable description
Severity ERROR or WARNING

Field is the identifier to work from. It is stable, it is what the in-product help is keyed on, and it is what to quote when escalating.

Rule failures

Key Meaning Fixed by Statutory Action
val/required A required field arrived empty you No Supply the value at source. The Field names which one
val/gstin_format A registration number is not 15 characters in the valid pattern you No Correct it in the master data
val/hsn_format Classification code length invalid — goods need 4, 6 or 8 digits; services need 4, 5 or 6 you Yes — CBIC classification master Correct the code in the item master
val/doc_no_format The document number begins with a disallowed character — 0, - or / you Yes — Rule 46(b), CGST Rules Change the ERP numbering format. This is a legal requirement on serial numbering
val/max_items More than 1,000 line items on one document you No Split the document. The limit is the government's
val/export_pos_state An export document does not carry the required Place of Supply state code you Yes — Sections 10 to 13, IGST Act Set the correct code for exports. A tax position; confirm with the tax lead
val/preceding_doc_date A credit or debit note references an original dated on or after itself you No The original must predate the note. Correct the reference or the date
val/round_off_bound Round-off is outside the accepted range you No Round-off must fall within a narrow band. A large value means an arithmetic fault upstream

Required fields

A document is rejected if any of these is empty. The Field value in the error names which.

Header:

Doc_no · GSTIN · Tran_SupTyp · Doc_Typ · Doc_Dt · Val_TotInvVal · Val_AssVal · Tran_Typ

Supplier block: BillFrom_Gstin · BillFrom_LglNm · BillFrom_Addr1 · BillFrom_Loc · BillFrom_Pin · BillFrom_Stcd

Buyer block: BillTo_Gstin · BillTo_LglNm · BillTo_Addr1 · BillTo_Loc · BillTo_Pin · BillTo_Stcd · BillTo_Pos

Per line: Doc_no · item_SlNo · Item_PrdDesc · Item_IsServc · Item_HsnCd · Item_UnitPrice · Item_TotAmt · Item_AssAmt · Item_GstRt · Item_TotItemVal

The dispatch-from block

Dispatch-from fields describe goods leaving from somewhere other than the registered address. The block is optional as a whole — but once any part of it is used, the rest becomes required:

ShipFrom_Nm · ShipFrom_Addr1 · ShipFrom_Loc · ShipFrom_Pin · ShipFrom_Stcd

This catches integrations out. A mapping that populates one dispatch-from field "just in case" makes the whole block mandatory, and every ordinary invoice then fails.

Where a failed document goes

It is quarantined, not discarded. It appears in the Correction Cockpit with its per-field messages, where it can be fixed and promoted back into the pipeline. Promotion re-runs validation; a document that still fails returns to quarantine.

This is why "the invoice disappeared after upload" is nearly always quarantine rather than loss.

Fix at source, not in the cockpit

Correcting a document in the cockpit fixes that document. If the cause is a mapping rule, a master data fault, or an ERP configuration, the next batch brings the same failures.

Cause Fix
One document is wrong Correct it in the cockpit
Every document from one ERP fails the same way Fix the mapping template
Every document for one counterparty fails Fix the party master
Every document with a particular item fails Fix the item master
A whole batch fails Fix the source, then reload

Validation

Check Pass condition
The failing field is identified You are working from Field, not only Message
The cause is at the right level Distinguish a document fault from a mapping or master data fault
The fix is verified The corrected document promotes successfully
Recurrence is prevented If systemic, the source is fixed, not just the instances
Volume is monitored A rising rejection rate is investigated as a cause, not absorbed as work

Troubleshooting

Symptom Cause Action
Documents disappear after upload Quarantined Open the Correction Cockpit
val/required for a field the ERP does send Mapping targets the wrong path, or the value is empty in this document Inspect the mapped payload
Every invoice fails on dispatch-from fields The mapping populates part of the block unnecessarily Populate the whole block or none of it
val/gstin_format on a valid registration Whitespace, case, or a truncated value in the mapping Trim and check the full length
val/hsn_format on a code that looks right Leading zeros stripped somewhere in the chain Carry codes as text end to end
val/doc_no_format on every document The ERP series begins with a disallowed character Change the format. It is a legal requirement, not a preference
val/round_off_bound at volume An arithmetic fault upstream, not a rounding preference Fix the calculation at source
val/preceding_doc_date on credit notes The reference date is wrong or defaulted Correct the reference
A document keeps returning to quarantine The correction did not address the actual failure Re-read every message; several may apply
Rejections rise after an ERP change The change altered a mapped field Compare a current payload against one from before the change