Errors

All errors share one envelope:

{
  "error": {
    "code": "invalid_url",
    "message": "Must be a https://www.zillow.com property URL",
    "request_id": "8f7a3b..."
  }
}

error.code is stable and machine-readable. Match on it; do not parse message. Include request_id when reporting issues.

Status code mapping

Code	When
`missing_api_key`	No `Authorization` header
`invalid_api_key`	Bad format, unknown, or revoked
`quota_exceeded`	Monthly quota hit
`rate_limited`	Per-minute rate limit hit
`invalid_url`	URL doesn’t match the expected Zillow pattern
`invalid_address`	Address too short or malformed
`invalid_zpid`	Non-numeric zpid
`missing_input`	Required body field absent
`invalid_status`	Bad value for `status`
`invalid_extract_units`	Bad value for `extract_units`
`not_found`	Property/job/webhook not found
`job_not_ready`	Job is not in `succeeded`
`job_not_found`	UUID does not match an account-owned job
`upstream_timeout`	Provider call exceeded timeout
`upstream_error`	Provider returned non-2xx
`invalid_json`	Body could not be parsed as JSON

Reads (GET) are safe to retry on 5xx and 429.
Writes (POST async) create new jobs — retrying creates a new job. Use request_id correlation in your logs to match attempts.
Webhooks include a per-attempt counter (attempt) and a timestamp; treat any single delivery as at-least-once.