If you are building an ERP, billing application, accounting system, or GST automation workflow for an Indian business, e-invoicing is not just a PDF-generation problem.
Your application has to send structured invoice data to an Invoice Registration Portal (IRP), pass validation, receive an Invoice Reference Number (IRN), and handle the resulting QR code and invoice data correctly.
That means a technically valid API request can still fail because the underlying GST data is incorrect.
Here are some of the most common GST e-invoice API problems that developers and finance teams should understand.
What actually happens when an e-invoice is generated?
A typical workflow looks something like this:
- The invoice is created in an ERP or billing application.
- Relevant invoice data is converted into the required format.
- The data is submitted to an authorised IRP.
- The IRP validates the invoice.
- If validation succeeds, an IRN is generated.
- The signed invoice/QR information is returned.
- The ERP stores the IRN and updates the invoice.
The important point is that the IRP isn't simply storing whatever your application sends.
It validates the data.
The current IRP documentation lists errors for incorrect GSTINs, invalid HSN codes, incorrect tax calculations, duplicate IRNs, invalid unit codes and several other data problems.
Why e-invoice API integration often fails
The interesting part is that many failures aren't really “API problems”.
They are data-quality problems.
For example, your API may be working perfectly, authentication may succeed, and the JSON may be syntactically valid.
But if the GSTIN is inactive or the tax calculation doesn't match the taxable value and rate, the invoice can still fail validation.
This is why GST automation needs both software validation and tax-data validation.
- Duplicate IRN requests
One common problem is accidentally submitting the same invoice multiple times.
The IRP documentation identifies error 2150 as “Duplicate IRN”.
This can happen when an application retries an API request without first checking whether the previous request actually succeeded.
For example:
Request sent → timeout → application assumes failure → request sent again.
If the first request actually generated the IRN, the second request can create a duplicate-registration problem.
A better implementation should store the response and IRN immediately after successful registration and have a proper retry/reconciliation mechanism.
Don't build your retry logic around “send again and hope”.
- Incorrect GSTIN
GSTIN validation is another common source of failure.
A business might have:
- Supplier GSTIN
- Customer GSTIN
- Ship-to GSTIN
- Dispatch-from details
These values should not simply be copied from an old invoice.
A customer may have changed registration status, a branch may have a different GSTIN, or the GSTIN may have been entered incorrectly.
The IRP documentation specifically lists errors for inactive, cancelled or invalid GSTINs.
From a software perspective, maintaining a reliable master-data system is just as important as writing the API integration itself.
- Wrong HSN code
An invoice can fail because the HSN being submitted is invalid or doesn't correspond to the nature of the transaction.
The IRP lists invalid HSN errors and also validates whether the HSN is appropriate for goods or services.
This is why HSN shouldn't be treated as a free-text field that every user can type differently.
A better system can maintain a controlled HSN master and validate the selected code before sending the invoice to the IRP.
- Tax calculation doesn't match
This is probably one of the most interesting problems for developers.
Suppose an item has a taxable value of ₹1,00,000 and a GST rate of 18%.
The tax calculation needs to correspond to the taxable value and applicable rate.
If your application sends a CGST/SGST or IGST amount that doesn't match the expected calculation, the IRP can reject the request.
The current IRP error documentation includes validations for taxable value, CGST, SGST and IGST totals as well as line-level tax calculations.
So don't calculate invoice totals independently in multiple places.
Ideally, one calculation engine should determine:
Line taxable value → tax rate → tax amount → invoice totals.
This reduces the chance of rounding and aggregation differences.
- CGST/SGST vs IGST confusion
Another common issue is sending the wrong type of tax.
For example, an inter-state transaction generally requires IGST rather than CGST and SGST.
The IRP documentation specifically identifies cases where CGST/SGST are incorrectly passed for an inter-state transaction.
This means your application needs a reliable place-of-supply and transaction-state logic.
Don't simply determine tax based on whether the customer is marked “local” or “outstation” in the UI.
The underlying GST data should drive the calculation.
- Invalid unit codes
Quantity-related errors can also cause e-invoice failures.
The IRP uses defined unit quantity codes. If your accounting software stores units such as “PCS”, “Piece”, “Nos”, “Units” or other custom descriptions, your integration may need to map those internal values to the accepted codes.
The IRP specifically lists invalid Unit Quantity Code errors.
A good integration therefore needs a mapping layer rather than directly sending whatever unit description appears in the ERP.
- Missing mandatory fields
JSON validation can fail before you even reach the business logic.
E-invoice data has mandatory and conditional fields.
The IRP documentation explains that schema-level validation can reject missing mandatory fields, invalid data types, incorrect lengths and unsupported values.
This is why client-side validation is useful.
Instead of:
Generate JSON → send to API → wait for error
you can implement:
Input → local validation → GST validation → JSON generation → API request.
That makes debugging much easier.
What should a developer log?
One mistake I see in tax integrations conceptually is treating the API response as the only thing that matters.
For production systems, you should have a proper audit trail.
Depending on your architecture and data-protection requirements, useful records can include:
- Internal invoice ID
- Document number
- Document date
- GSTINs
- API request status
- IRP response status
- IRN
- Error code
- Error message
- Timestamp
- Retry count
- Cancellation status
You should also make sure sensitive information isn't unnecessarily exposed in application logs.
The goal is to make it possible to answer:
“Why did invoice INV-1042 fail?”
without manually searching through five different systems.
Design for idempotency
This is especially important for e-invoice API integrations.
Imagine this sequence:
Your application sends an invoice.
The IRP processes it.
Your server doesn't receive the response because of a temporary network problem.
Your application thinks the request failed.
Then it submits the same invoice again.
That's where duplicate processing can happen.
A robust architecture should be designed to safely handle retries and reconcile the invoice state before submitting the same document again.
In other words:
Don't assume “no response” means “no IRN”.
This is a software-engineering problem with tax-compliance consequences.
Don't hard-code GST rules everywhere
GST rules and IRP validations evolve.
For example, the IRP production release in February 2026 introduced relaxation of certain Total Item Value and tax-amount validations for specified RSP-based invoices with document dates on or after 1 February 2026.
That is a good reminder for developers:
Don't scatter GST rules throughout the codebase.
Instead, consider keeping tax configuration and validation logic modular where practical.
This makes future changes much easier to implement and test.
A practical architecture
A basic e-invoice integration could be organised like this:
Billing UI
↓
Invoice Service
↓
GST Validation Layer
↓
E-Invoice Payload Builder
↓
IRP API Client
↓
Response Handler
↓
Invoice/IRN Database
↓
Accounting & E-Way Bill Workflows
The important part is separation.
Your UI shouldn't need to know every IRP validation rule.
Your API client shouldn't be responsible for calculating business taxes.
Your accounting system shouldn't depend on parsing an error message from an API response.
Each layer should have a clear responsibility.
Testing checklist before going live
Before deploying an e-invoice integration, test at least these scenarios:
- Valid B2B invoice
- Inter-state transaction
- Intra-state transaction
- Credit note
- Debit note
- Multiple line items
- Different GST rates
- Invalid GSTIN
- Invalid HSN
- Invalid unit code
- Incorrect tax amount
- Missing mandatory field
- Duplicate invoice submission
- API timeout
- Retry after timeout
- IRN response received but database update fails
- Invoice cancellation workflow
That last scenario is particularly important.
What happens if the IRP successfully generates an IRN but your application's database crashes before saving it?
Your recovery process needs to be able to reconcile the invoice rather than blindly generating another request.
Final thoughts
GST e-invoicing is a good example of why tax compliance and software engineering increasingly overlap.
A developer may see an API integration.
An accountant may see an invoice.
A business owner sees a customer transaction.
The system has to make all three perspectives work together.
The most common e-invoice problems aren't necessarily complicated programming bugs. They can be as simple as an incorrect GSTIN, HSN, unit code, tax amount or duplicate request.
The current IRP documentation provides specific validation codes for many of these situations, which makes it possible to build better pre-validation and error-handling into your application.
If you're developing GST billing software in India, don't treat e-invoicing as “just another API”.
Treat it as a compliance-critical integration.
Validate before sending.
Make retries safe.
Store IRNs properly.
Log failures without exposing unnecessary sensitive data.
And keep your GST rules configurable enough to adapt when the system changes.
Top comments (0)