Error handling for effective and efficient use of APIs

The E Way Bill and E-Invoice Systems managed by NIC has been functioning smoothly with their robust infrastructure. However, it has come to our attention that many API calls result in errors, leading to unproductive usage of compute resources and network bandwidth and impacting overall system performance. To maximize the utilization of system resources, it is crucial to address and minimize these errors.

To tackle this issue, we have implemented proactive measures such as automated emails and direct communication with taxpayers to raise awareness about the errors they encounter and provide guidance on how to avoid them. This approach has successfully eliminated erroneous API calls from these taxpayers, indicating that the root cause lies in the code implementation or application bugs. We have also documented the causes and resolutions of these errors in the developer’s portal.

We are developing a strategy to identify the major error generators to ensure smooth and efficient services for genuine API calls. We will inform the respective taxpayers about the issues and allow them a specific period to rectify them. If the issues persist beyond the designated time frame, their access to the E-Invoice System will be automatically blocked.

A fundamental requirement for API integration is comprehensive logging of request and response data, along with continuous monitoring. Successful API calls should be flagged to avoid redundant payload submissions, while failed calls require analysis of the response and application of necessary corrections before resubmitting the payload. Providing detailed error information is intended to facilitate the necessary actions to rectify the errors before reattempting API access and completing the task. It has been observed that the same erroneous request payload is often reused without the required corrections, leading to resource wastage without resolving the underlying problem.

To assist API users in effectively and efficiently utilizing the API system, we would like to highlight some of the most common errors and their recurring patterns. API users can optimize their usage and minimize error occurrences by understanding these patterns and taking appropriate measures.

Through proactive error handling and continuous improvement of the API integration process, we aim to enhance the overall user experience, reduce unproductive API calls, and ensure the smooth functioning of the E Way Bill and E-Invoice Systems.

Duplicate IRN: Error Code 2150

One common error encountered is the Duplicate IRN, which is indicated by error code 2150. This error occurs when multiple IRNs are attempted to be generated for the same combination of supplier GSTIN, document type, document number, and financial year. Once an IRN is successfully generated, any subsequent requests with the same payload will result in an error stating “duplicate IRN.” 

To assist users, if they fail to receive the response when the IRN is initially generated, attempting to generate the IRN again with the same payload will return the details of the previously generated IRN. This information can be utilized to obtain the complete details of the E-Invoice.

Some of the scenarios have been shown in the following table

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
2			12/15/2020	Request 1	90
3			12/16/2020	Request 1	91
4			12/17/2020	Request 1	92
5			12/18/2020	Request 1	92
6			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.
8			12/19/2020	Request 2	161
9		GSTIN2	12/15/2020	Request 1	11
10			12/16/2020	Request 1	21
11			12/16/2020	Request 2	9
12			12/19/2020	Request 1	14
13		GSTIN3	12/15/2020	Request 1	334
14		GSTIN2	12/15/2020	Request 2	333
15	Client Id 3		12/16/2020	Request 1	27	Same GSTIN sending different payloads multiple times on the same day
16			12/16/2020	Request 2	47
17			12/16/2020	Request 3	45
18			12/16/2020	Request 4	45
19			12/16/2020	Request 5	42
20			12/16/2020	Request 6	53
21			12/16/2020	Request 7	54

Resolution

To avoid generating duplicate IRNs (Invoice Reference Numbers) in an e-invoicing system, follow these steps:

• Save Response and Update Flag: After generating an IRN, save the API response and update a flag against the invoice. This flag indicates that the IRN has been generated for that specific document and should not be used again to call the API. By updating the flag, you can prevent the generation of duplicate IRNs.

• Retrieve IRN Details in Case of Response Failure: If, for any reason, the user is unable to receive the response after generating the IRN, attempt to retrieve the response again. The subsequent attempt will provide the IRN details along with the error response. The response will include the IRN number, the time of IRN generation, and the associated act number. This information can be used for further processing or querying using the Get IRN Details API.

• Limit Duplicate Requests: To prevent unnecessary duplication, ensure that no more than two requests with the same payload are generated to generate the IRN. By adhering to this limitation, you can avoid generating multiple IRNs for the same invoice.

By implementing these steps, you can effectively handle the issue of duplicate IRNs and maintain the integrity of the e-invoicing system.

Duplicate requests:

Duplicate requests can lead to application errors when the server receives multiple requests simultaneously. Since each request is treated as new at that moment, the duplicate check may pass, causing the system to attempt to save all the Invoice Reference Numbers (IRNs) associated with the duplicate requests. However, due to the simultaneous nature of the requests, the system can only successfully save the data from one of the requests, failing to protect the data from the other duplicate requests.

The same issue also applies to authentication requests, where separate tokens may be generated for each duplicate submission. This can lead to the generation of multiple tokens, causing conflicts and resulting in ‘Invalid Token’ errors during the authentication process.

To address this issue, it is essential to implement mechanisms to detect and handle duplicate requests effectively. This can involve utilizing unique request identifiers, implementing concurrency controls, and ensuring atomic operations during data processing. By managing duplicate requests properly, you can prevent application errors and maintain the system’s integrity.

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
2		GSTIN 2	12/21/2020 0:52	Request 1	2
3	Client Id 2	GSTIN1	12/14/2020 15:26	Request 1	2
4		GSTIN 2	12/16/2020 13:57	Request 1	2
5		GSTIN 3	12/16/2020 13:57	Request 1	2
6		GSTIN 4	12/16/2020 13:57	Request 1	2
7		GSTIN 5	12/16/2020 13:59	Request 1	2

Resolution:

To address the issue of duplicate requests in an e-invoicing system, follow these resolutions:

• Avoid Simultaneous Requests: Take precautions to prevent firing identical request payloads simultaneously. Coordinate the timing of requests to ensure they are sent at different times. This can be achieved by introducing slight delays between requests or implementing a request queue system to manage the order of requests.
• Introduce Delay between Requests: Even if the server responds quickly, it is advisable to introduce a delay between sending the same request payload. This ensures that each request is processed individually and reduces the likelihood of duplicate requests. Adding a few seconds of delay can mitigate potential conflicts.

Handle Multiple Client Applications/Systems/Threads:

If multiple client applications, systems, or threads are involved, special care should be taken to avoid picking the same payload by more than one application or system simultaneously. Implement synchronization mechanisms, such as locks or semaphores, to coordinate access and prevent multiple entities from using the same payload simultaneously.

By implementing these resolutions, you can reduce duplicate requests in the e-invoicing system. It is essential to consider your system’s specific architecture and requirements when implementing these measures.

Inactive GSTIN or GSTIN not available:

Inactive GSTIN refers to a Goods and Services Tax Identification Number (GSTIN) that is inactive or deactivated. A non-existing GSTIN refers to a GSTIN that does not exist in the system or is not registered with the relevant authorities.

When multiple requests with the same payload contain inactive GSTINs or non-existing GSTINs, the API consistently returns the same error response. This means that unless the incorrect GSTINs are corrected, or the respective GSTIN data is synchronized between the GSTN Common portal (the central repository for GST-related information) and the E-Invoice System (the system responsible for generating e-invoices), the error response will persist.

To resolve this issue, it is necessary to ensure the accuracy and validity of the GSTIN data. This includes validating the GSTINs before submitting requests, verifying their active status, and synchronizing the GSTIN data between the GSTN Common portal and the E-Invoice System. Correcting any inactive or non-existing GSTINs and ensuring proper synchronization can resolve the error response, and the e-invoicing process can proceed smoothly.

Resolution:

To address the issue of inactive or non-existing GSTINs in an e-invoicing system, follow these steps:

1. Validate GSTIN Data: Before submitting multiple requests with the same payload, ensure that the GSTIN data is validated and accurate. Verify that the GSTINs provided are active in the GSTN (Goods and Services Tax Network) Common portal.
2. Sync GSTIN Data: Ensure the GSTIN data is synced between the GSTN Common portal and the E-Invoice System. If there are discrepancies or inconsistencies in the GSTIN data, it can lead to errors. Make sure that any changes or updates to GSTIN information are reflected accurately in both systems.
3. Correct Inactive or Non-existing GSTINs: If the error response indicates inactive or non-existing GSTINs, take the necessary steps to correct the GSTINs. This may involve updating the GSTIN data, verifying its validity, or contacting the relevant authorities to rectify any issues with the GSTINs.
4. Error Handling and Response: Handle the error response appropriately when encountering inactive or non-existing GSTINs. Provide clear error messages to users, indicating that the GSTINs need to be corrected or that they do not exist in the system. This will help users understand the issue and take the necessary actions to resolve it.

By following these steps, you can address the issue of inactive or non-existing GSTINs and ensure the smooth functioning of the e-invoicing system.

Date	GSTIN	Count
12/23/2020	GSTIN1	23222
12/27/2020	GSTIN1	20379
12/30/2020	GSTIN1	8152

PIN Code does not belong to given State Code:

The error “PIN Code does not belong to given State Code” occurs when the PIN code provided does not match the corresponding state code. It signifies an inconsistency between the provided PIN code and the associated state code.

To resolve this issue, it is essential to provide the correct combination of PIN and state codes. Verify that the PIN code corresponds to the proper state per the official postal code database. Cross-check the PIN code and state code combinations to ensure accuracy and consistency.

By providing the correct and valid combination of PIN and state codes, you can avoid errors and ensure that the accurate location information is associated with the given data.

In the provided examples:

1. The PIN code 846008 of the buyer does not belong to their state with State Code 6. However, it should have been State Code 10.
2. The PIN code 670101 of the buyer does not belong to their state with State Code 29. Instead, it should have been State Code 32.
3. The PIN code 635109 of the buyer does not belong to their state with State Code 29. It should have been State Code 33.

To resolve these errors, the correct State Codes should be provided for the respective PIN codes. The State Codes should align with the actual states associated with the given PIN codes. By ensuring the accurate mapping of PIN codes and State Codes, the errors can be rectified, and the information will be aligned correctly.

Date	GSTIN	Count
12/23/2020	GSTIN1	14408
12/28/2020	GSTIN1	15470
12/30/2020	GSTIN1	14468

Resolution:

To address the issue of invalid HSN (Harmonized System of Nomenclature) codes in e-invoicing, follow these resolutions:

1. Validate HSN Code: Before sending requests, ensure that the HSN code provided is valid and accurate. Cross-check the HSN code against the official HSN code database or the relevant authorities to ensure its correctness. Verify that the HSN code exists and is appropriate for the goods or services being invoiced.
2. Educate Users: Provide guidance and education to users on the correct usage of HSN codes. Ensure they understand the importance of using valid HSN codes and the potential impact of incorrect or non-existent HSN codes on invoicing.
3. Implement HSN Code Validation: Incorporate an HSN code validation mechanism within the e-invoicing system. This can involve integrating with a reliable HSN code database or implementing an algorithm to validate the HSN codes users enter.
4. Error Handling and Response: Handle the error response for invalid HSN codes appropriately. Provide clear error messages to users indicating that the HSN code entered is incorrect or does not exist. Additionally, offer suggestions or prompts to help users identify and select the correct HSN code for their goods or services.

By implementing these resolutions, you can minimize the occurrence of invalid HSN codes in e-invoicing requests and ensure accurate reporting and compliance with relevant regulations.

Invalid HSN Code:

Invalid HSN Code refers to a situation where the provided HSN (Harmonized System of Nomenclature) code in an e-invoicing system is incorrect or does not exist. The HSN code is a standardized code for classifying goods or services for taxation and trade purposes.

In the examples given:

1. The HSN code “39200000” is considered invalid and should have been “3920”.

2. The HSN code “73170000” is deemed invalid and should have been “7317”.

3. Due to incorrect formatting, The HSN code “94054099, 94054000, 85371099, 39269000” is invalid.

To resolve the issue of invalid HSN codes, the following actions can be taken:

1. Validate HSN Codes: Ensure that the HSN codes are accurate and correspond to the relevant goods or services being invoiced. Cross-check the HSN codes against the official HSN code database or consult the appropriate authorities to verify their correctness.

2. Educate Users: Provide guidance and education to users on the proper usage of HSN codes. Ensure they understand the significance of using valid and accurate HSN codes and the potential implications of incorrect or non-existent codes.

3. Implement HSN Code Validation: Integrate an HSN code validation mechanism within the e-invoicing system. This can involve utilizing a reliable HSN code database or an algorithm to validate the entered HSN codes.

4. Error Handling and Response: Handle the error response for invalid HSN codes appropriately. Inform users that the provided HSN code is incorrect or does not exist. Additionally, offer assistance or suggestions to help users identify and select the correct HSN code for their goods or services.

By implementing these measures, invalid HSN codes in e-invoicing requests can be minimized, ensuring accurate reporting and compliance with relevant regulations.