Avalara Developer Network Developer avaTax

11.1 - Detecting a Dropped Connection

In Chapter 1.3 - Troubleshooting, we briefly explained how to handle AvaTax error messages. Errors related to offline tax calculation can be more complex because sometimes you may receive an error from AvaTax and in other times you may receive an error from your operating system or software development suite indicating that a connection has been 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 the error EntityNotFoundError from the API, you have searched for a document that does not exist. This error should be shown to the user; it will help them determine how to proceed. They may have mistyped the document code.

{
  "error": {
    "code": "EntityNotFoundError",
    "message": "Document with ID 'TESTINGCO - 100' not found.",
    "target": "HttpRequest",
    "details": [
      {
        "code": "EntityNotFoundError",
        "number": 4,
        "message": "Document with ID 'TESTINGCO - 100' not found.",
        "faultCode": "Client",
        "helpLink": "/avatax/errors/EntityNotFoundError",
        "severity": "Error"
      }
    ]
  }
}

If you receive an error message that indicates that your API call has failed, or your connection has been broken, or there has 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:

TransactionModel t;
try {
    t = Client.CreateTransaction(model);
} catch (AvaTaxError err) {
    ... code to respond to the error ...
}

A dropped connection will produce a different kind of error - for example, AspNetCore produces an 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 have 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 end 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 should select an appropriate timeout value for your needs. We cannot 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 you should be able to execute:

Test Case - 11.1.1

Setup

  • Call CreateTransaction with the option $include=ForceTimeout

Assertions

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

Now that you’ve simulated a timeout in your application, the next step is to decide whether to retry your transaction or fallback to a default tax rate calculation.