Zillow API errors: decide what to fix, review, or retry

Do not retry every failed request

A useful Zillow API error policy separates invalid input, account problems, identity ambiguity and temporary service failures. Repeating the same request is appropriate for only some of these cases. Others need a corrected address, a new key or a decision by the account owner.

PropertiesAPI returns an error object with a machine-readable code. Use the status and code together. Log a request correlation reference and the category of input, while keeping API keys and sensitive lookup details out of general application logs.

Build a small decision table

Keep the policy close to the HTTP client so web pages, background jobs and CSV imports behave consistently. Use the current endpoint documentation as the source of truth for codes and response details.

Bound retries by attempts and elapsed time

Use exponential backoff with jitter for failures that are actually retryable. Respect a Retry-After response. Set both a maximum attempt count and an overall deadline, then put the item into a visible deferred or failed state.

An error tied to a service-wide budget or disabled lookup service may need a longer wait or operator action. A missing field or invalid address is not fixed by increasing retry frequency. Distinguish these from a brief network interruption.

attempt request
if success:
    validate property identity and save result
else if input, auth, account or ambiguity error:
    stop and show the required action
else if documented transient error and budget remains:
    wait for Retry-After or bounded backoff with jitter
    retry
else:
    retain a visible failed or deferred result

Treat client timeouts as uncertain outcomes

If your client disconnects before receiving a response, it does not know whether the server completed the request. Do not promise users that nothing happened simply because the browser timed out.

Use an appropriate timeout for the endpoint, keep a local request record, and reconcile results and account usage before replaying large jobs. A cache may make repeat property requests inexpensive, but that is different from an exactly-once guarantee across every network failure.

Handle batch errors at the item level

A batch can return successful and failed items together. Save successful items immediately, then classify failures independently. Replaying the whole batch can obscure progress and cause avoidable work.

Retain the original row ID, returned index, error code and next action for each failed item. A user should be able to see whether a row needs an address correction, account action or another attempt. “Something went wrong” is not enough for a file containing many homes.

Test error behavior before launch

Use deterministic fixtures for validation, authentication, credit exhaustion, ambiguous addresses and transient failures. Test both a Retry-After response and a response without one. Verify that retries stop.

Keep a small live acceptance check separate from fixture tests. Fixtures prove that your application handles known shapes; they do not establish source availability, live latency or account configuration. Track those separately and avoid turning a development success into an uptime promise.