> ## Documentation Index
> Fetch the complete documentation index at: https://docs.homelogs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fast diagnosis for common integration failures

## 403 on every request

Likely cause: missing/invalid API key.

Check:

* `X-API-Key` header is present
* key is from the correct environment
* key has not been rotated/revoked

## 422 validation errors

Likely cause: invalid query parameter format.

Common examples:

* `state` not 2 letters
* invalid date format (must be `YYYY-MM-DD`)
* invalid enum (`sort`, `geo_type`)

## 404 with valid-looking request

Likely cause: no matching location or empty scoped data.

Try:

* broader `query` and a state filter on `/v1/locations/resolve`
* remove optional filters (`permit_type`, `status`, date bounds)

## 429 under load

Likely cause: per-key usage plan exceeded.

Mitigate:

* implement backoff + jitter
* reduce parallel calls
* batch workflows where possible

## 503 from `/v1/permits/search`

Likely cause: permits dependency unavailable/misconfigured.

Action: retry and alert ops; include `request_id`.