Handling warnings

The warnings field on every response is a list of free-text advisories about the lookup. They’re not errors — the rate is still authoritative — but they tell you something the caller should know.

Most common warning today:

place_input_mismatch — the customer-supplied city name doesn’t match the actual jurisdiction at the address. Example: the customer typed “Frisco” but the address resolves to unincorporated Denton County. Other providers that trust the customer’s city name return the wrong rate; TaxQL surfaces this explicitly.

response = client.lookup(state="tx", address="...", city="Frisco", zip="75068")

for warning in response.warnings:
    if "place_input_mismatch" in warning or "not the actual jurisdiction" in warning:
        # Surface to the customer; consider re-prompting for address review
        print(f"⚠ {warning}")

Other current warnings (ZIP-mode advisories about straddled jurisdictions, period-coverage gaps, fallback resolutions) are returned as plain strings. The set is small and stable; new warnings will be added as the API surfaces more edge cases.

Full content coming soon — including a complete warning-code registry and recommended caller-side handling for each.