Docs · Basics

Errors and rate limits

HousingFeed APIs answer errors as JSON with a stable code, limit requests per key or per IP with standard headers, and never break a field within a version.

Errors are JSON with a stable machine-readable code. Feed API errors also carry a request_id; quote it when you write to us.

{
  "error": {
    "code": "version_gone",
    "message": "Version 2026-09-14 is no longer available. Start again from the current version (2026-10-19)."
  },
  "request_id": "6f1c..."
}

Feed API

HTTP status	code
`400`	`bad_request`
`401`	`unauthorized`
`402`	`payment_due`
`402`	`subscription_lapsed`
`402`	`trial_ended`
`404`	`not_found`
`404`	`page_not_found`
`405`	`method_not_allowed`
`410`	`since_gone`
`410`	`version_gone`
`429`	`rate_limited`
`503`	`not_published`
`503`	`unavailable`

Rate limit per key: 1,200 requests an hour and 6,000 a day, shared with the MCP feed tools. A full pass of a national file takes a few hundred requests. Above the limit the API answers 429 with Retry-After.

Sample endpoint

HTTP status	code
`429`	`RATE_LIMITED`
`502`	`UPSTREAM_UNAVAILABLE`
`503`	`NOT_CONFIGURED`

About 30 calls per 10 minutes per IP, with RateLimit-* headers on every response.

Versioning

Endpoints on housingfeed.com are version 1 under /api/v1/. Fields are added, never renamed or removed, within a version; a breaking change ships as /api/v2/ with at least six months of overlap.

Want the full file for your market?

Tell us your cities and what you are building. You get a sample in the production format and the listing count for your markets, usually within one business day.

Request a sample