Error Handling:
TaxBandits API uses the commonly used error codes to stream the success or failure message to an API request. If validation checks fail during the creation of the business, the field errors will return the information in the Response, which may be handled at the client's end.
What are the validations?
● Mandatory/format validations, agency-specific data validations Ex: size, type, allowed characters, etc.,
● IRS/SSA Business Rules Validation (Math validations, Form conditions)
● USPS address validation (only for the postal orders)
When are the validations checked?
● These validations are checked during the following API Endpoint method calls
a. Create —During the creation of the form. The validations must pass before the form will be created.
b. Update — Like the Create method, validations must pass before the form is updated.
c. Validate — This method performs validations on the created documents.
d. Transmit — When you call the Transmit method, we validate the form before it is transmitted.
e. ValidateForm — The validations are performed without creating the form.
How are the errors communicated?
● The errors are communicated in the Response of Create, Update, Validate, ValidateForm, and Transmit methods.
● 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 correct it?
● 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 containing errors and call the methods 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 subjects the data to some 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
To process individual records, the data is subjected to business validation checks. 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
Business Object fields
The Business Object is a common field in all the forms supported by TaxBandits API. So, when you file a new Form W-2, 941, 1099MISC, or 940, you can use the same Business Object created in any Endpoint and in other Endpoints too.
Since the Business Object is built for all types of forms, there will be optional fields which 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 on the response. You must use the Submission ID the next time you are using API calls like Update, Get, List, etc.
If a single submission has multiple records (Forms), a unique Record ID will be generated for each of the records (Forms). You can use the Record ID the next time when you are making the API calls like Update, Get, List etc. to work on a particular record.
Business ID or TIN
When you create a Form W-2/1099MISC, a unique business ID will be created for the business. In the future, you can just use the business ID to work with that particular business.
You can either use the business ID or business's EIN/SSN to reference a business created. Please note: The EIN/SSN is unique to a business under the user account. If there is already a business with the same EIN/SSN, the details will be merged during the API Create method call.
Webhook URL — Reactivation
If the Webhook delivery (Status or PDF) fails 18 times continuously when we try to send the Webhook responses to your URL, our system will stop sending the Webhook response and your webhook URL will be disabled on our end. Then you must change it back to Active by logging in 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 call 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. You do not have to use the Status and GetPDF methods each time to check the status of the returns and download the forms. We don't encourage continuous polling of our servers/APIs.
Sequence Number
The sequence number under the Return object can be used for your reference. The sequence number should be unique for all the records in a single submission.
You can refer to 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
Since our e-file system has an in-built 4 hours delay, this 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 within 24 hours. Make sure, the Rejections posted by us on the Webhooks reach the taxpayer within the time frame. Although it is applicable to MeF platforms, we uphold the same timelines across all the Form types.
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 address from your end, it is always advised to send the new IP to us before sending requests to our API. Only requests from whitelisted IPs can reach the API. Authentication errors will be thrown if you send requests from a non-whitelisted IP address.
TaxBandits E-file Rejections
After a form is transmitted using Transmit Method, 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 applied?
● These validations will be applied to the return before it is submitted directly to the appropriate Agency by TaxBandits E-File System once it is 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 can be used in the case that a user needs to cancel the submission or recall the return to edit it. Once the E-File system takes over, the processing of the form can not be stopped. 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.
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" method.
● 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 correct errors?
● You can update the fields containing errors and use the Update, Validate and Transmit methods 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 above), our system will hand it over to the Federal Agency for processing. Although we experience very few rejections, we still get a few, typically for the following reasons:
● Duplicate filing for the same tax year or quarter. The client could have paper filed or e-filed it elsewhere (Check on the Agency's database).
● The Business name and EIN does not match (Checked on the Agency's database)
● The return should not have been filed for legal reasons.
When are the validations checked?
These errors will be checked on the Federal Agency's side 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 greatly. It generally depends on the volume of returns that are trying to process at a given time. Our system picks up the errors from the Federal Systems and is mandated to communicate to clients within 24 hours.
● These errors are communicated either by Webhook or developers can pick up the errors using the Form Endpoint "Status" method. We prefer the Webhook method of communicating the errors
● The Status of the Return will change to "Rejected".
How to correct 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
These are rejections from the respective state agencies. Rules vary completely for each state and this can become highly complicated. Some states require unique values for the employee W2 data and some states demand specific information from the employer (Tax Liability, Tax Deposit information) before processing the W2 forms. While rejections are rare, here are the most common reasons why they occur.
● 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 checked?
These errors will be checked on the State Agency's side after we submit the return to them.
How are these errors communicated?
States process the returns at an unpredictable pace. 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 Form Endpoint "Status" method. Again, we prefer the Webhook method of communicating the errors.
● The Status of the Return will change to "Rejected".
● The response time of these errors solely depends on the state.
How to correct it?
● 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 the error handling techniques we offer.
Follow our instructions on best practices for a better understanding of how to file your returns.