> This page is for Documentation, version Integration guides (default).
> For other versions, use one of these documentation indexes:
> - Integration guides (default): https://avalara.ferndocs.com/docs/integration-guides/llms.txt
> - Refactor guides: https://avalara.ferndocs.com/docs/refactor-guides/llms.txt
> - Get certified: https://avalara.ferndocs.com/docs/get-certified/llms.txt
> - Agent to Agent (A2A): https://avalara.ferndocs.com/docs/agent-to-agent-a2a/llms.txt
> - AI use cases: https://avalara.ferndocs.com/docs/ai-use-cases/llms.txt
> - API versioning: https://avalara.ferndocs.com/docs/api-versioning/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://avalara.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://avalara.ferndocs.com/_mcp/server.

# Handle errors

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`**

```json title="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.

> **Tip**
>
> 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.