Skip to content
Zillow API

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

HTTP Meaning
200 Success
201 Created (e.g. webhook)
202 Accepted, async job started
204 No content (e.g. webhook revoke)
400 Client validation failed
401 Missing or invalid API key
402 Out of credits
403 Account suspended or operation not allowed on current plan
404 Resource not found
409 Job not in expected state
429 Rate limit hit
502 Upstream call failed
504 Upstream call timed out

Common error codes

Code When
missing_api_key No Authorization header
invalid_api_key Bad format, unknown, or revoked
out_of_credits Account credit balance reached 0, top up at /app/billing or upgrade
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 A required body/query field is absent (e.g. POST /v1/search with no filters and no searchUrls; by-url with no url)
invalid_filters filters is present but unusable, most commonly a search with no bbox (a free-text location/city alone is not enough), or a malformed bbox/range object
invalid_search_url A searchUrls[].url is not a usable Zillow search URL, it must contain a ?searchQueryState=... query parameter (pretty URLs like /austin-tx/houses/ are rejected)
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

Search validation errors (worked examples)

A search must carry a bounding box or a pre-built Zillow URL. These are the three ways a search request fails validation before it ever reaches upstream (all return 400):

// missing_input, nothing to search on
POST /v1/search  { "maxItems": 50 }
→ { "error": { "code": "missing_input", "message": "..." } }


// invalid_filters, free-text location only, no bbox
POST /v1/search  { "filters": { "location": "Austin, TX", "status": "for_sale" } }
→ { "error": { "code": "invalid_filters", "message": "..." } }


// invalid_search_url, URL has no searchQueryState
POST /v1/search  { "searchUrls": [{ "url": "https://www.zillow.com/austin-tx/houses/" }] }
→ { "error": { "code": "invalid_search_url", "message": "..." } }

Fix: supply filters.bbox (or bbox=w,s,e,n on the GET wrapper), or a searchUrls[].url that contains ?searchQueryState=.... See Search for how to obtain a bbox.

Idempotency and retries

  • 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.