docs / 06

Errors

The API returns JSON errors with a stable error code and a human-readable message.

Error shape

A rejected request returns a JSON body with at least an error code and a message.

{
  "error": "invalid_fips",
  "message": "county FIPS must be exactly five digits",
  "fips": "abc"
}

Status	Meaning
200	Success.
201	Created (trial token issued).
400	Malformed input: an invalid FIPS, status or state filter.
401	Missing, invalid or expired credential.
402	The trial token has no credits remaining.
403	The token is revoked, or the caller is not an admin.
404	Unknown county, unknown token id, or unknown path.
409	An active trial token already exists for the account.

Code	HTTP	Raised when
invalid_status	400	status is not one of the five coverage statuses. The body lists allowed.
invalid_state	400	state is not a two-letter abbreviation or two-digit FIPS.
invalid_fips	400	/api/counties/:fips is not exactly five digits.
invalid_county_fips	400	/api/parcels county_fips is not exactly five digits.
not_found	404	No tracked county with that FIPS, or no revocable token with that id.
trial_already_active	409	The account already has an unexpired trial token.
missing	401	No Authorization: Bearer header was provided.
invalid	401	The bearer token is not recognised.
expired	401	The bearer token is past its expiry.
exhausted	402	A trial token has no credits remaining.
revoked	403	The bearer token has been revoked.

An unknown county:

{
  "error": "not_found",
  "message": "No county with FIPS 00000",
  "fips": "00000"
}

An exhausted trial token:

{
  "error": "exhausted",
  "message": "The API token has no credits remaining."
}