In the previous Error handling section, we briefly explained AvaTax handles error messages. Errors related to offline tax calculation can be more complex because sometimes you can receive an error from AvaTax, and other times you receive an error from your operating system or software development suite indicating that a connection has dropped.

When you receive an error message from AvaTax, the best practice is to display that error to the operator or visitor and allow them to determine how to proceed. For example, if you receive an EntityNotFound error from the API, you've searched for a document that doesn't exist. Show this error to the user; it will help them determine how to proceed. They may have mistyped the document code, for example.

View example

If you receive an error message that indicates that your API call has failed, your connection has been broken, or there's been a timeout, your error message may come from the operating system rather than AvaTax. For example, using the AvaTax SDK in C#, this code will catch errors sent from AvaTax:

View example

A dropped connection produces a different kind of error. For example, AspNetCore produces a WinHttpException when a connection is dropped using HttpClient. Our task is to identify how our operating system or programming language exposes a connection error. Once you've identified this error, your code must trap the exception and ensure that you can respond correctly and prevent the exception from being exposed to the user.

But how do we test this code? If a connection interruption is an unpredictable occurrence, how can you evaluate it? AvaTax provides an interesting feature called ForceTimeout. This feature is intended to allow you to fine-tune your client-side timeout logic, and reliably cause a timeout that you can use for integration testing.

When you use the ForceTimeout feature, AvaTax will do the following:

Delay for 30 seconds

Throw an error of type ForceTimeoutError

We recommend that your application selects an appropriate timeout value for your needs. We can't tell you exactly what timeout value is best for you; but in our experience, interactive web applications tend to have a shorter timeout, and desktop accounting programs tend to have a longer timeout. Here’s the test that you should be able to implement:

Setup

Call CreateTransaction with the option $include=ForceTimeout.

Assertions

If your code has a timeout value selected, expect an operating-system or programming-language-specific error message related to the timeout of this API call.

Detect a dropped connection