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 immediately or wait before retrying.

Set the Timeout Setting

Set your timeout setting appropriately. Run a single line item request and record the response time. Add 2 to 3 seconds to the response time to get a recommended client-side Timeout Setting value. Scale the timeout setting value accordingly for transactions containing multiple line items.

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.