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. On an export, see Export documents — the buyer has no GSTIN
val/pincode_format A party PIN code is not exactly 6 digits — supplier, buyer, dispatch-from or ship-to you No Correct the value. Most often Excel dropped a leading zero — format the column as Text. On an export the buyer PIN rule is relaxed; see Export documents
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
val/line_tax_mismatch A line's IGST/CGST/SGST does not equal its taxable value × GST rate (±₹1) you No Fix the rate or the amount — whichever is wrong for the product. NIC rejects this at IRN generation; it is now caught at load

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

The ERP ingest API (agent push and mapped-ERP ingest) checks the identical set of buyer-block fields, but reports them under NIC's own field names rather than these column names — BuyerDtls.Addr1, BuyerDtls.Loc, BuyerDtls.Pin, BuyerDtls.Stcd, BuyerDtls.Pos (and BuyerDtls.LglNm, BuyerDtls.Gstin). Same requirement, different label depending on which door the document came through. One exception: a delivery challan / bill of supply / bill of entry (CHL/BIL/BOE, the EWB-only route) does not require the buyer's Addr1/Loc/Pin/Stcd — only Excel/IGM and a tax invoice (INV) on the ERP path enforce them.

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

Export documents

An export supply — Tran_SupTyp of EXPWP (with payment of tax) or EXPWOP (without) — goes to an overseas buyer who holds no Indian registration. Two buyer-block rules relax accordingly, matching what the government schema and the ERP ingest API already accept:

Field On an export
BillTo_Gstin Not required. Leave it empty or send the literal URP. A malformed non-URP value is still rejected
BillTo_Pin The 6-digit PIN format rule (val/pincode_format) is not applied — a foreign address has no Indian PIN. The government convention is 999999. The value must still fit the column (6 characters), so send 999999 or leave it blank

The supplier, dispatch-from and ship-to PINs are Indian addresses and are not relaxed — val/pincode_format still applies to them on an export.

BillTo_Pos must still be 96 (Other Country) — see val/export_pos_state below. URP is accepted only for BillTo_Gstin and ShipTo_Gstin, never for GSTIN or BillFrom_Gstin.

This relaxation is keyed on Tran_SupTyp. A document that should be an export but carries the wrong supply type will still fail the buyer-GSTIN rules — fix the supply type first.

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.

Before validation — "Upload Prevented" at staging

A file-upload job is parsed into staging tables before any validation runs. A value that is wider than its destination column fails the whole job there, with Upload Prevented and a per-row message — no document reaches the Correction Cockpit, because none was staged.

The message names the row, the document number, the column, and the value. The commonest cause is a shifted column in the spreadsheet: a party name or address sitting in a *_Gstin column because the bill-to or ship-to block was filled one column across. This happens most on exports, where the ship-to (a port or CFS) has no GSTIN, so data entry starts from the name. When the offending value in a *_Gstin column is clearly text, the message says so and points to the *_LglNm column it belongs in.

Fix: put the name in ShipTo_LglNm / BillTo_LglNm, leave the *_Gstin column blank for an unregistered party, and check the rest of that block is not shifted. Then re-upload.

Where a failed document goes

Once staged, a document that fails validation 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/gstin_format or val/required on BillTo_Gstin for an export The document reached validation as a domestic supply Check Tran_SupTyp is EXPWP/EXPWOP; then the buyer GSTIN may be blank or URP — see Export documents
"Upload Prevented … ShipTo_Gstin allows 15 characters but got …" with a name as the value The ship-to block is filled one column across; the name is in the GSTIN column Move the name to ShipTo_LglNm, leave ShipTo_Gstin blank, un-shift the rest of the block — see Before validation — staging
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
val/line_tax_mismatch on an export line The line carries a GST amount but is zero-rated, or the rate column was dropped in the mapping Zero-rated export lines must have every tax amount set to 0; otherwise set the correct rate
val/line_tax_mismatch appeared only after this release The check was added — it was previously caught only by NIC at IRN generation The document was always invalid; fix the rate/amount at source
Rejections rise after an ERP change The change altered a mapped field Compare a current payload against one from before the change