Skip to main content

Error Handling & Rejection Handling in TaxBandits API

· 10 min read
TaxBandits Tech

TaxBandits API has employed various validation processes and error-handling methodologies to streamline API requests. If validations fail during the creation of the business, the field errors will return this information in the response.

What are the validations performed?​​

● Mandatory/format validations, agency-specific data validations (Eg: size, type, allowed characters, etc.,)

● IRS/SSA Business Rules Validation (Math validations, Form conditions)

● USPS address validation (Only for the postal orders)

When do the validations occur?​​

● These validations are checked during the following API Endpoint requests:

a. Create —The Create requests will be validated before the form is created.

b. Update — The Update requests will be validated before the form is updated.

c. Validate — This method performs validations on the created documents.

d. Transmit — When you call the Transmit method, the form will be validated before it is transmitted.

e. ValidateForm —The validations are performed without creating the form.

How are the errors communicated?​

● If there are any errors in the API requests, they will be communicated in the Response of Create, Update, Validate, ValidateForm, and Transmit endpoints.

● These errors will be communicated instantly in the Response JSON, and each error has a unique Error Code that is used to track and resolve them.

How to fix the errors?​​

● We will provide the Field Mapping, API Business Rules, IRS Business Rules, and Error Message documentation to help you resolve the validation errors that occur on your side.

● You can update the fields that contain errors and make the requests again (Create, Update, Validate, or Transmit).

Error Structure

{
<← HTTP Status Code Fields →>
"StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
<← Submission Detail →
"SubmissionId": "6a30078c-7e5f-4db0–862a-d5e1266363f0",
<← Form Success Details & Business Validation Errors →>
 "FormRecords": {
<← Collection of Form Success Details →
 SuccessRecords": {
 . . .
 },
<← Collection of Business Validation Error Details →
 "ErrorRecords": {
 . . .
 },
<← Collection of Data Validation Error Details →
 "Errors": {
 . . .
 }
}

HTTP Status Codes

HTTP status codes are reported back in the response JSON. The chart below shows how the HTTP status codes are grouped:

Data validation errors

Before processing individual records, the API performs certain mandatory data validation checks. Any errors that are observed will be reported under the object "Errors".

"Errors": {
<<-- Error on an incorrect TIN format -->
    {
        "Id": "F00-100088",
        "Name": "Business.EINorSSN",
        "Message": "Enter a valid EINorSSN”
    }
}

Business validation errors

The data will be subjected to business validation checks, and any errors that are observed will be reported under the object “ErrorRecords”.

<<-- Collection of Business Validation Error -->
"ErrorRecords": {
<<-- Business Validation Errors on Record with Sequence 8 -->

    "RecordId": "0e6b053a-3e67-4559-a09f-5631bd06f5e9",
    "Sequence": "8",
    "Errors":
    {
       
<<-- Error on Recipient First Name required -->

        "Id": "F00-100239",
        "Name": "Recipient.FirstPayeeNm",
        "Message": "FirstPayeeNm is required",
           }
},

Best Practices

TaxBandits incorporates certain best practices for handling errors and rejections.

Business Object fields​

The Business Object is a common field for all the forms supported by TaxBandits API. So, when you file a new Form W-2, 941, 1099-MISC, or 940, you can use the same Business Object in multiple endpoints.

Since the Business Object is built for all types of forms, there will be optional fields that are not relevant to a particular form under the Business Object. You can leave those fields blank as they are non-mandatory.

Submission IDs and Record IDs​

Whenever you submit a request, a unique Submission ID will be sent to you in the response.

If a single submission has multiple records (Forms), a unique Record ID will be generated for each of the records (Forms), which can be used for future references.

Business ID or TIN​

When you create a Form W-2/1099-MISC, a unique business ID will be created for the business, which can be used for future references of the EIN/SSN of the particular business created.

Note : The EIN/SSN is unique for each business under the account. If there is already a business with the same EIN/SSN, the details will be merged when the API Create endpoint is requested.

Webhook URL — Reactivation​

If a Webhook delivery (Status or PDF) fails 18 times continuously, our system will stop sending the Webhook response, and your Webhook URL will be disabled at our end. Then you must change it back to active by navigating to the console settings (Webhook Settings) page and revalidating the URL.

Store the IDs​

Submission ID, Business ID, and Record ID must be stored in order to request the consequent APIs.

Use Webhook to get statuses and pdf​

We strongly recommend that you configure the Webhook in a way that the status of the form and pdfs are received automatically so that you don’t have to use the Status and GetPDF methods each time to check the status of the returns and download the forms. We don't recommend continuous polling of our servers/APIs.

Sequence Number​

The sequence number under the Return object should be unique for all the records in a single submission.

You can use the Submission ID and Sequence number the next time you want to refer to the particular return (Update, Get, Status, etc.)

Cancel or Callback submission within 4 hours after Transmission​

Our e-file system has an in-built 4 hours delay, which allows the developer to cancel/recall the forms for any corrections before the returns are submitted to the agency.

Note: This option will be disabled during the last week of January.

Client communication within 24 hours​

As per the IRS guidelines, it is the responsibility of the Software Provider(TaxBandits) to take reasonable steps to inform the taxpayer of the rejection (if any) within 24 hours.

Although it is applicable only to MeF platforms, we uphold the same timelines across all the Form types.

Therefore, we always make sure the rejections posted by us on the Webhooks reach the taxpayer within the time frame.

Refer IRS Publication for more information about this https://www.irs.gov/pub/irs-pdf/p4163.pdf

Whitelist IP Addresses (Live)​

If there is a change in IP at from your end, it is always advised to send the new IP to us before sending requests to our API. Because only the requests from whitelisted IPs can reach the API,and authentication errors will occur if you send requests from a non-whitelisted IP address.

TaxBandits E-file Rejections

After a form is transmitted using Transmit endpoint,the TaxBandits E-File system takes over and does a series of validations and sends out the rejections:

● Field format and business rules validations on the converted data (as per the Agency Schema).

● Checks for duplicate filings in TaxBandits

● Agency specific file format validations (EFW2, FIRE or MeF XML)

● Proprietary system validations

● USPS address validations (only for the postal orders)

● Any missed validations from Stage 1

When are the validations performed?​​

●These validations will be carried out before the return is submitted directly to the appropriate agency by TaxBandits E-File System after being transmitted using the API.

● We have a built-in delay of 4 hours before the E-file System takes over and performs error checks. This delay allows you to cancel the submission or recall the return to edit it if required.

Note : This built-in delay will not be enforced during the 5 days of January when there is a massive volume of data running through our system processes.

Once the E-File system takes over, the processing of the form can not be stopped.

How are the errors communicated?​

● These errors are communicated either via Webhook or the developer can pick up the errors using the Form Endpoint "Status" endpoint.

Note :Webhook is the preferred way because the processing timings are unpredictable and we don't encourage polling of our API from your client application.

● These errors will be communicated within 24 hours after the return is Transmitted to our system.

● The Status of the Return will change to "Rejected"

How to fix the errors?​​

● You can update the fields containing errors and use the Update, Validate, and Transmit endpoints to retransmit the return.

● The corrections are applied to the same W-2/1099 Form — no new form or correction forms are necessary.

● The credits will not be deducted for the forms that are Rejected and Retransmitted.

Federal Agency Rejections

These rejections come directly from the IRS (for 1099) or SSA (for W2). Once the returns pass through E-File validations (as described above), our system will hand them over to the Federal Agency for processing. Here are some of the common reasons for rejections:

● Duplicate filing for the same tax year or quarter

● The Business name and EIN does not match

● The return should not have been filed for legal reasons

When are the validations performed?​​

These errors will be checked on the Federal Agency after we submit the return to them.

How are these errors communicated?​

The amount of time that it takes agencies to process returns can vary depending on the volume of returns. Our system picks up the errors from the Federal Systems and is communicated to clients within 24 hours.

● These errors are communicated either by Webhook, or developers can pick up the errors using the “Status” endpoint.

● The status of the return will change to "Rejected".

How to fix the errors?​​

● You can update the fields with the errors and use the methods Update, Validate, and Transmit to retransmit the return.

● The corrections are applied to the same W-2/1099 Form — no new form or correction forms are necessary.

● The credits will not be deducted for the Forms that are Rejected and Retransmitted.

State Agency Rejections

The rejection criteria may vary completely for each state, and this can become highly complicated. Some states require unique values for the employee W-2 data, and some states demand specific information from the employer (Tax Liability, Tax Deposit information) before processing the W2 forms. Here are the most common reasons for rejections.

● State agency-specific rejections based on state Business Rules

● State Reconciliation form field errors

● The State ID number didn't match the state database

When are the validations performed?​​

The State Agency will validate the returns once they are submitted.

How are these errors communicated?​​

Our system picks up the errors from the state systems for processing.

● These errors are communicated either via Webhook, or the developer can pick up the errors using the "Status" endpoint

● The status of the return will change to "Rejected".

● The response time of these errors solely depends on the state.

How to fix the errors?​​

● You can update the fields containing errors by using the methods Update, Validate and Transmit to retransmit the return.

● The corrections are applied to the same W-2/1099 Form — no new form or correction forms are necessary.

● The credits will not be deducted for the forms that are Rejected and Retransmitted.

Conclusion

Handling errors & rejections are made easier with streamlined error-handling techniques.

For any further assistance, feel free to contact our 24*7 South Carolina-based support team at 704.684.4751 or send us an email at developer@taxbandits.com.