Avalara Developer

AvaTax returns standard HTTP status codes. On failure, the body contains an error object with a machine-readable code, a human-readable message, and a details array pinpointing the problem.

Error response

{
  "error": {
    "code": "AddressError",
    "message": "Address is not valid.",
    "target": "IncorrectData",
    "details": [
      {
        "code": "AddressError",
        "number": 308,
        "message": "The address is not deliverable.",
        "severity": "Error",
        "refersTo": "Addresses[0]"
      }
    ]
  }
}

Status codes

Status	Meaning	What to do
`400`	Malformed request or invalid data	Fix the payload; inspect `details[].refersTo`
`401`	Missing or invalid credentials	Recheck your account ID and license key
`403`	Authenticated but not permitted	Confirm the account’s subscriptions and permissions
`404`	Resource not found	Verify the company code and transaction code
`429`	Rate limit exceeded	Back off and retry with exponential delay
`500`	Service error	Retry idempotently after a short delay

Retrying safely

Calculation is deterministic, so retrying transactions/create with the same document code is safe — AvaTax returns the existing transaction rather than duplicating it.

Respect the limit

On 429, read the Retry-After header if present and wait at least that long.

Back off exponentially

Double the delay on each retry (1s, 2s, 4s…) with jitter, up to a sensible ceiling.

Give up gracefully

After a few attempts, surface the error to the caller rather than blocking checkout.

Log the full error.code and details on failures. The refersTo field points at the exact line or address that caused the problem, which makes support tickets far faster to resolve.