Every quarter we get a call that starts the same way: "Our e-invoices are failing and the dispatch gate is blocked." Almost none of these are integration problems. They are master-data problems that only became visible when a government API started validating them.
The failures are nearly always the same four
- Invalid or missing HSN codes. The IRP validates HSN against the item's tax rate. A wrong code that your accountant tolerated for years fails instantly.
- GSTIN state code mismatch. The first two digits of the buyer's GSTIN must match the place-of-supply state. Address masters drift; GSTINs do not.
- Unit of measure not in the approved list. "Nos", "PCS" and "pieces" are not interchangeable. The IRP accepts a fixed vocabulary.
- Rounding disagreements. Line-level versus invoice-level rounding differing by a paisa will reject the whole document.
Fix the data before you touch the integration
Run a validation pass over your item and party masters and score them. We use a simple gate: no cutover until HSN coverage is 100%, GSTIN format validity is 100%, and UOM values map cleanly to the approved list. That report takes a day to build and saves weeks.
Design for the failure path first
An IRN request will fail sometimes — the portal has outages, and it does not care that your truck is waiting. Your system needs:
- A queue, so dispatch is never blocked on a synchronous call.
- Idempotency, so a retry cannot produce two IRNs for one invoice.
- A visible exception desk where failed documents sit with the actual error message, not a generic "failed" flag.
- A cancellation window rule — IRNs can only be cancelled within 24 hours, and your process must respect that.
Reconcile continuously, not at filing time
The expensive version of this problem is discovering in month three that 400 invoices never got an IRN. A daily reconciliation between your sales register and the IRN log, with a count and value match, turns that into a same-day fix.
Compliance integrations fail loudly at the worst possible moment. Build the exception handling before the happy path — you will use it more than you expect.