1.3 - Troubleshooting

Whenever AvaTax is unable to respond to your API call, the software will present you with an AvaTax error code. Each error code contains a hyperlink to a web page with more information about the error. As you learn the AvaTax API, it’s important that you understand how to read and interpret these error codes.

Handling Error Messages

We’ve designed the AvaTax error messages to clearly tell you what went wrong, what you can do about it, and how to proceed. You can read a list of all AvaTax REST error codes on the developer website - and each error message contains within it a hyperlink to the page for that specific error. Our community forums team monitors all comments on the developer website, so if you see anything confusing, write us a comment - we’d love to improve our documentation!

When an AvaTax API call produces an error, it responds using the standard HTTP error response codes. Response codes between 400 and 499 are called Client Errors, and they indicate that you made a mistake in your API call. Response codes between 500 and 599 refer to internal errors within AvaTax itself; each internal error is automatically logged and reported to our development team for triage.

If your program gets an HTTP response code between 400 and 499, here’s how to proceed:

  • Parse the error message using a JSON parsing engine.
  • Display the summary of the error to the user.
  • Link the user to the documentation page that explains the error.
  • Allow the user to make a change to their request, or retry their action.

For example, let’s examine how to handle an authentication error. If a developer forgets to pass authentication credentials to an AvaTax API, they will probably see the error message AuthenticationIncomplete:

Request: GET /api/v2/companies/ Response: 401 Unauthorized{  "error": {    "code": "AuthenticationIncomplete",    "message": "Authentication Incomplete.",    "target": "HttpRequestHeaders",    "details": [      {        "code": "AuthenticationIncomplete",        "number": 34,        "message": "Authentication Incomplete.",        "description": "You must provide an Authorization header of the type Basic or Bearer to authenticate correctly.  ",        "faultCode": "Client",        "helpLink": "/avatax/errors/AuthenticationIncomplete",        "severity": "Exception"      }    ]  }}

Your next step should be to display an error message in your product:

  • Begin by displaying the value error.message in your user interface. This helps the user understand the context of the problem without taking up too much space.
  • If your user interface has room for more details, display the value contained in error.details[0].description and the error.details[0].helpLink. This would allow the user to see the link "You must provide an Authorization header of the type Basic or Bearer to authenticate correctly."
  • Some API calls can include more than one error. For example, if a user is creating a transaction with ten invoice lines, you will receive a list of error messages, one per mistake. Depending on your user interface, you may wish to parse and display all error messages, or only display the top one.

In the case of an error, it’s critical to handle the error and enable the software to continue. If your program has a user interface, you should allow the user to retry or cancel the API call. Your customers may be working offline or with an interrupted Internet connection, and they need to get their work done even if they can’t use AvaTax at the moment. We’ll cover offline behavior more in Chapter 11 - Calculating Tax Offline, but for the moment let’s review how to properly handle error messages.

Here’s a test case that causes an error message to occur. We will call the QueryCompanies API with an incorrect filter, which produces an error message. Try this API call and make sure your program can display the error message correctly:

Test Case 1.3.1 - Handling Errors


  • Call QueryCompanies with the following parameters:
    • $filter = id = 'abc'


  • You will receive an error message:
    • Title: "Error parsing $include parameter."
    • Message: "The field named 'CompanyId' is type System.Int32 and cannot be compared to 'abc'".
  • Your product will display an error message showing this error message.
  • The error message should make it clear to a user that they have attempted to filter on a numeric value but have instead provided an alphabetic string.
  • Create Transaction:
    GET https://sandbox-rest.avatax.com/api/v2/companies?$filter=id = 'abc'

Now that your software is able to display the error message correctly, let’s discuss how to solve common problems.

Identifying a Firewall or Proxy Server Problem

If your software is unable to contact AvaTax, pretty much any API call you make will produce an error. So let’s begin by explaining how we can identify whether a connection problem exists.

First, please visit the AvaTax API server from your desktop computer or mobile phone. You should try both of these two URLs, one for sandbox and one for production:

If your connection is working correctly, you should see a web page similar to the following:

If you can’t see this page on your desktop computer at work, but you can see this web page from a mobile phone on the public Internet, you may have a networking issue. There’s a chance your office has a firewall or proxy server that enforces some limits on your network connectivity. Contact your corporate IT department for more information.

Testing Authentication

If you receive an authentication error, a good place to start is the Ping API. You can call this API whenever your program starts, to check to ensure that it can contact the AvaTax server - because ping will never return an error message even if you don’t provide any authentication. If your Ping call fails, you know you are having trouble with your internet connection.

Here’s how to use ping:

Test Case 1.3.2 - Ping API


  • Call the AvaTax Ping API


  • The Ping API returns a JSON object with the following information:
    • version: A string similar to "" indicating the version of the AvaTax server.
    • authenticated: A boolean value indicating whether your API call was successfully authenticated.
    • authenticationType: A string with information about the authentication method you used, if any.
    • If your API call was successfully authenticated, information about the authenticated user will appear in the fields authenticatedUserName, authenticatedUserId, and authenticatedAccountId.
  • Ping:
    GET https://sandbox-rest.avatax.com/api/v2/utilities/ping

When your program detects that a ping call has failed, it should notify the user that it can’t reach AvaTax, and ask them to check their Internet connection. If the ping call returns but the authenticated field is set to false, the user has probably mistyped their username or password and they should retry.

Before we move on, let’s look at a few other common troubleshooting steps you may encounter as you begin development:

Other Common Problems

Problem Type Steps to Diagnose
Routing Problems Do your routers have the latest software? Have they been rebooted recently, or are there too many hops between your network and the outside world?
  • If your network is using a direct connection with a local internet service provider, does your connection reset regularly?
  • If the connection is permanent or business-class, does your ISP offer metrics to help you measure response time?
  • If you have a more advanced network using Border Gateway Protocol routing, you would need to talk to your network engineering team. BGP issues are very challenging to review and are beyond the scope of this article.
Due to security issues, Avalara's servers do not respond to ping requests. This means that network traces from software like traceroute or tracert are not able to provide accurate route timings.
Authentication Problems Try using the Ping API, or switch to using an AvaTax SDK which has prebuilt and tested authentication code.
Firewall Problems To use AvaTax, you must enable access to all IP addresses identified by these DNS names: AvaTax is a dynamic product and its IP addresses may change regularly. AvaTax does not support firewalls that filter on individual IP addresses.
Ethernet Problems Check the quality of your wiring and the auto-negotiate settings on your ethernet devices. Bad wiring or devices with mismatched speed settings are easy to overlook! You can run netstat -s on a windows machine or ifconfig -a on a linux machine to detect whether an unusual number of bad packets are coming through your network. If you have a performance mismatch, try checking with your network administrator to see if the cabling can be improved.
Host Files / IP Address Hardcoding / DNS Caching AvaTax does not support hard coded IP addresses or host files. To use AvaTax, you must resolve DNS names dynamically. Your DNS server should respect the DNS time-to-live (TTL) values; Avalara publishes DNS TTL values designed to permit our operations team to adjust our connectivity in response to changing network conditions.
Proxy Server Problems AvaTax is not designed for environments using proxy servers. Proxy servers can cause latency and connectivity problems when calling high performance APIs like AvaTax. If your company policy requires a proxy server by policy, please consult your proxy provider for how to correctly configure the proxy to work with AvaTax.
DNS Time-To-Live Avalara makes changes to our domain name system records periodically. Your software should ensure that you respect the DNS time-to-live values, and that your software periodically contacts DNS to update its name lookups. Some software, including some Java JRE versions, may need to be updated to ensure the "ttl" or "time-to-live" values are correctly handled. If you experience problems with occasional DNS changes, please check the documentation for your operating system, programming language, or development environment to ensure your software handles TTL values correctly.
Need SSL Certificate Verification Some web clients (such as CURL for Windows) will require you to download the Avalara AvaTax SSL public keychain and install it into your client’s keychain repository. If the client program requests that you specifically accept and trust Avalara's web certificate, here's how to proceed:
  1. Go to VeriSign Root CA and follow the instructions.
  2. Save the file in your preferred directory named like "certs-ca-bundle.crt".
  3. Register that file following your standard certificate store process.