Errors

Errors are structured JSON — never made-up results. Invalid or unavailable queries return documented codes.

Envelope

Error response

{
  "detail": {
    "code": "PARCEL_NOT_FOUND",
    "message": "No parcel 9999999999999 in county 48201."
  }
}

Errors live under a detail key (FastAPI's convention). code is stable and machine-readable; message is for humans and may be omitted. Some errors carry only a plain-string detail (e.g. FastAPI validation errors on malformed query params).

Codes

HTTP	Code	When
400	`INVALID_INPUT`	Missing required filters or malformed query
401	`MISSING_API_KEY`	No X-API-Key header
401	`INVALID_API_KEY`	Unknown key
403	`API_KEY_REVOKED`	Key revoked
403	`ADMIN_REQUIRED`	Admin-tier endpoint with a non-admin key
404	`PARCEL_NOT_FOUND`	No parcel for (county_fips, account_number, year)
404	`COUNTY_NOT_FOUND`	Unknown county FIPS
404	`TAXING_UNIT_NOT_FOUND`	Unknown unit code
404	`COLLECTOR_NOT_FOUND`	Unknown collector id
404	`APPRAISAL_DISTRICT_NOT_FOUND`	Unknown district id
404	`KEY_NOT_FOUND`	Admin: unknown key id
409	`KEY_ALREADY_REVOKED`	Admin: revoking an already-revoked key
422	`INVALID_TIER`	Admin: tier not in free/standard/internal/admin
429	`RATE_LIMIT_EXCEEDED`	Over tier limit; Retry-After header set

Data-quality semantics

Null means unresolved, not missing. A taxing unit code that could not be resolved stays null — it is never guessed or dropped.
Values carry status. value_status distinguishes preliminary, certified and supplemented rolls; "no notice issued" is a distinct state from "notice value unknown".
History is archived on receipt. Certified values change year-round via supplements; every value row carries as_of.