Error handling

The Python SDK maps HTTP error responses to exception subclasses so you can except AuthError / except RateLimitError without inspecting status_code yourself.

Exception	HTTP	Retry?	What to do
AuthError	401	No	Prompt for a new key; don’t retry blindly
ValidationError	400, 422	No	Fix the request — exc.response_body has the detail
NotFoundError	404	No	Address couldn’t be resolved; try a different mode
RateLimitError	429	Yes (SDK auto-retries)	If you re-raise, honor exc.retry_after
ServiceError	5xx	Yes (SDK auto-retries)	Upstream issue; give up after max_retries
AmbiguousLookupError	— (client-side)	N/A	Walk response.rows manually

The SDK retries 429 and 5xx automatically with exponential backoff (default 3 attempts, honoring Retry-After). 4xx errors other than 429 raise immediately — there’s no point retrying a malformed request.

from taxql import (
    TaxQL, AuthError, RateLimitError, NotFoundError,
    ValidationError, ServiceError, TaxQLError,
)

try:
    response = client.lookup(state="tx", zip="75068")
except AuthError:
    raise SystemExit("Invalid API key. Check the dashboard.")
except RateLimitError as exc:
    # SDK already retried; this means it gave up
    raise SystemExit(f"Quota exhausted; retry after {exc.retry_after}s")
except (NotFoundError, ValidationError) as exc:
    log.error("Lookup failed: %s (body=%s)", exc, exc.response_body)
except ServiceError:
    # Upstream is down — defer to a retry queue
    enqueue_for_later(...)
except TaxQLError as exc:
    log.exception("Unexpected SDK error", extra={"status": exc.status_code})

Full content coming soon — including caller-side retry strategies for batch processing.