Avalara Developer Network Developer communications

Chapter 6.2 - Retry or Fallback

After your application detects a timeout or an error, it must next make a decision whether to retry the transaction or fallback to cached tax types and tax rates.

Retry a Transaction

Retry your transaction a few times if timeouts are still being returned:

  1. Retry the transaction
  2. Wait 1 second and retry the transaction
  3. Wait several seconds and retry the transaction

It’s important that you don’t retry so often that your attempts are mistaken as a denial-of-service attack. Limit your retries to 5 to 10 attempts to prevent a backlog of concurrent requests and allow system time to recover.

Things to consider when retrying a transaction:

  • Some applications attempt to reuse HTTP connections. In the event that you experience a connection disruption, we suggest creating a completely new connection for the next attempt
  • You may not know whether REST v2 received your original request if you receive a timeout. The request may be received and processed successfully by REST v2, but you do not receive the response. In this case, using the Commit/Uncommit functionality is helpful
    • Set a unique Document Code (doc), such as a GUID, in your CalcTaxes request
    • Update the Document Code (doc) to a new unique value if a timeout or other error is detected again
    • Commit everything at once using the Commit endpoint once all transactions contained in your bill run are successfully processed

What if AFC Geo is unresponsive?

If you are using embedded geolocation (geo = true in a location object) as part of your CalcTaxes request and AFC Geo is not responding, the entire transaction fails. To resolve, turn embedded geolocation off (geo = false) and retry the transaction. The AFC Tax Engine determines the taxing jurisdiction based on the address information provided.

For more information, see Geocode Offline.


We recommend not using the embedded geolocation functionality on a regular basis since it impacts performance and can cause the CalcTaxes request to fail if AFC Geo is experiencing issues.

Fall back to cached tax data

Cache tax types and tax rates daily by running a set number of unique transactions that cover your business needs. In the event of a timeout or other type of error, fall back to these cached types and rates. The transactions that have used cached tax data need to be processed through REST v2 in order for that data to be available in the Customer Portal Data Explorer and for compliance reports.

Caching the tax data is only beneficial if your transactions are largely created the same way and can easily be identified as one of the unique transactions you ran at the beginning of the day. Tax type and tax rates are based on a number of characteristics:

  • Jurisdiction
  • Transaction and Service Types
  • Invoice Date
  • Other characteristics, such as customer type and sale type

Things to consider when falling back to cached tax data:

  • Tax types and tax rates vary by transaction/service type, jurisdiction rules, and other factors
  • You are obligated to remit the over-collected amount if you use a cached tax rate that is higher than the actual tax rate
  • You are obligated to remit all taxes collected in a jurisdiction even if you have an exemption or exclusion normally in place (in the event that REST v2 can't be reached and a client profile can't be applied to the transaction)

Whatever approach you select, the cardinal rule of tax auditors is what whatever amount of tax you collect, you must remit.

  • If you accidentally over-collect tax you must still remit the amount you collect
  • If you collect tax in a jurisdiction where you are not registered as a business, you must choose to either register your business and begin filing taxes or refund the tax collected to the customer
  • Contact Avalara’s Professional Services team for advice about tax over-collection policies suitable to your business - this Developer Guide is not a substitute for obtaining professional compliance advice