Error handling for effective and efficient use of APIs

As all are aware, NIC is running the E Way Bill and E Invoice Systems smoothly since the launch. Though NIC has the sufficient infrastructure to handle large number of transactions per day, as well as large number of transactions simultaneously during peak hours, close look at the transaction logs show that there have been large number of API calls that are unsuccessful due to certain errors. This large number of unproductive API calls will affect all the stake holders by consuming the compute resources and the network bandwidth and affecting the performance. The carefully designed system resources can be effectively utilized by reducing / nullifying the errors.

We have been monitoring and reaching out to the tax payers by way of automated emails and in some cases, we are contacting the tax payers and appraising them of the errors generated by them and how to avoid them. With this, the erroneous API calls from those tax payers have completely stopped. This indicates that the issue could be handled by writing proper code or fixing the bugs in the consuming application. We have also published the cause and resolution of the errors in the developer’s portal.

To mitigate this issue and to provide smooth and efficient services to the genuine API calls, we are working out a strategy to identify the top error generators, intimate the concerned tax payer about the issue, allow them to correct the same within certain period. If the issue is not resolved within the allowed period, the system would automatically block the access to the E Invoice System for that tax payer.

Basic requirement of API integration is logging the request and responses and monitoring the same. If the API call has succeeded, a flag has to be set so that the same payload is not sent again, if the call has failed, the response should be analyzed, required corrections have to be applied and only then the payload has to be sent to the server. Purpose of providing the error details is to facilitate necessary action to be taken before accessing the API again, to get the job completed. It is observed that the same erroneous request payload is used many number of times without applying the required correction. This will never solve the problem but consume the resources unnecessarily

Some of the top errors, the pattern of their occurrences are being highlighted here for the benefit of the API users to effectively and efficiently use the API system.

1. Duplicate IRN: One of the common errors is Duplicate IRN, with error code 2150. As it is not possible to generate multiple IRNs for the same combination of supplier GSTIN, doc. Type, doc. No. and fin. Year, once the IRN is generated, subsequent request to generate IRN with same request will throw an error saying duplicate IRN. For the benefit of the user, in case they have failed to receive the response when the IRN is generated for the first time, subsequent attempt to generate IRN with same payload would return the details of the IRN already generated. Using this information, one can get the complete details of the E Invoice.

Some of the scenarios have been shown in the following table

Number of requests with same payloads
(Same requests, different dates; Same date, different users; Same user, different requests)
S. No Client Id Taxpayer Date Request Count Remarks
1 Client Id 1 GSTIN1 12/14/2020 Request 1 43* Same tax payer using same request payloads on multiple days

12/15/2020 Request 1 90

12/16/2020 Request 1 91

12/17/2020 Request 1 92

12/18/2020 Request 1 92

12/19/2020 Request 1 91
7 Client Id 2 GSTIN1 12/19/2020 Request 1 253 Different GSTINs under same GSP making multiple requests with same as well as different payloads.

12/19/2020 Request 2 161
GSTIN2 12/15/2020 Request 1 11

12/16/2020 Request 1 21

12/16/2020 Request 2 9

12/19/2020 Request 1 14
GSTIN3 12/15/2020 Request 1 334

12/15/2020 Request 2 333
15 Client Id 3 GSTIN2 12/16/2020 Request 1 27 Same GSTIN sending different payloads multiple times on the same day

12/16/2020 Request 2 47

12/16/2020 Request 3 45

12/16/2020 Request 4 45

12/16/2020 Request 5 42

12/16/2020 Request 6 53

12/16/2020 Request 7 54


• Once the IRN is generated, the response should be saved and a flag should be updated against the invoice to indicate that the IRN is generated against this document and should not be used again to call the API.

• Even if the user is not able to receive the response after getting the IRN generated, the second attempt itself will provide the IRN details along with the error response. The response includes the IRN number, time of generation of IRN, act. No. The IRN number from the same may be used to get the further details of the E Invoice using the Get IRN details API

• So, there should not be more than 2 requests with same request payload to generate the IRN

2. Duplicate requests: It is observed that there are simultaneous requests (received at the server exactly at the same instance of time). This will create an application error. Since each request is a new request at that point of time, duplicate check passes and system tries to save all IRNs and then it fails to save other request data except one. Similar issue is applicable for authentication requests where separate tokens will be generated resulting in ‘Invalid Token’ error.

Simultaneous hits
(Different GSP, Tax payer, Date and Payloads)
S. No Client Id GSTIN1 Date Request Count Count 
1 Client Id 1 GSTIN1 12/19/2020 17:35 Request 1 2
GSTIN 2 12/21/2020 0:52 Request1 2
3 Client Id 2 GSTIN 1 12/14/2020 15:26 Request 1 2
GSTIN 2 12/16/2020 13:57 Request 1 2
GSTIN 3 12/16/2020 13:57 Request 1 2
GSTIN 4 12/16/2020 13:57 Request 1 2
GSTIN 5 12/16/2020 13:59 Request 1 2


• Take care of not to fire same request payloads simultaneously.

• Though the server responds within a second, it is always advisable to use same request payload after few seconds.

• If multiple client applications or multiple client systems or threads are being used, care should be taken to avoid picking same payload by more than one application or system or thread.

3. Inactive GSTIN or GSTIN not available: Multiple requests with same payload having same inactive GSTINs / non existing GSTINs. The API continues to give the same error response unless the GSTIN is corrected or the respective GSTIN data is synced between GSTN Common portal and E Invoice System.

No. of transactions by a GSTIN on sample dates
Date GSTIN Count
12/23/2020 GSTIN1 23222
12/27/2020 GSTIN1 20379
12/30/2020 GSTIN1 8152

The user has to check the correctness of the GSTIN used and check whether the GSTIN is active on the day of the document date. If yes, still the problem continues, the GSTIN has to be synced in E Invoice system from the GSTN common portal using the following alternatives

• In case there is a response with error code 3028 or 3029, the correct ness of the GSTIN should be checked on the E Invoice portal -> Search -> Tax payer and if required use the option "Update from GST Common Portal"

• Use "Get GSTIN Details" API to check the availability and status of the GSTIN and if required, use the "Sync GSTIN details from Common Portal" API to sync the data between GSTN and E Invoice system for the given GSTIN

4. PIN Code does not belong to given State Code: The PIN code given does not belong to the state provided. The correct PIN codes and State code combination should be provided wherever applicable

No. of transactions by a GSTIN on sample dates
Date GSTIN Count
12/23/2020 GSTIN1 14408
12/28/2020 GSTIN1 15470
12/30/2020 GSTIN1 14468


1. "Pincode -846008 of Buyer does not belong to his/her State - 6 "
-- State code should have been 10

2. "Pincode -670101 of Buyer does not belong to his/her State - 29"
-- State code should have been 32

3. "Pincode -635109 of Buyer does not belong to his/her State - 29"
-- State code should have been 33


• State wise PIN code list, as per E Invoice database is available for download in MS Excel file at E Invoice portal -> Search -> Master Codes.

• The same may be downloaded incorporated in the user application

• User has to send correct combination of PIN code and State Codes

5. Invalid HSN Code: Many requests are received where the HSN code is wrong or does not exist.


1. "HSN code(s)-39200000 is invalid" Should have been 3920

2. "HSN code(s)-73170000 is invalid" Should have been 7317

3. "HSN code(s)-94054099,94054000,85371099,39269000 is invalid" Wrong format


• The list of HSN codes used in the E Invoice system are available at E Invoice portal -> Search -> Master Codes.

• The HSN code should be sent as it is shown in the master list.

• There should not be prefixing zeros, if it is shown as 4/6 digit code, four/two more zeros should not be suffixed to make it 8 digit which does not exist in the master etc.