Errors and troubleshooting

What each status code means, and how to read the message the API sends back.

Every BuildData error returns the same shape, so you can handle them all the same way:

{
  "detail": "limit must be at most 500 (got 1000). Use offset, or cursor for deep pagination, to retrieve more."
}

The detail string names the parameter at fault and, where there is one, the nearest valid value. Log it: it is written to be read by a person.

Status codes

Common mistakes

• An unknown city slug returns 422 naming the nearest real slug. Call /{entity_type}/coverage for every slug in a dataset.
• A misspelled parameter returns 422 with a suggestion. Parameter names that are not close to a real one are ignored, so a filter you invented will silently do nothing.
• An empty results array is not an error. It means the filters matched nothing. Widen the date range or drop a filter to tell the difference between a bad query and a quiet week.
• 504 means the query was too broad, not that the API is down. Add a municipality or a date range and retry.
• On the free tier, the newest 30 days are not there. Responses carry a free_tier object saying so, and a record inside the window returns 403 rather than 404 when you ask for it by id. Everything older is included in full.
• A point searches an area around itself. lat and lng with no radius_km search 1 km around the point, and the response echoes the radius_km that was applied. Send one of your own to widen or narrow it: ?lat=43.6532&lng=-79.3832&radius_km=5. One coordinate without the other is still a 422. For every record at one address rather than everything within a kilometre of it, call /property with the address and skip the geocoding step.

Rate limits

Every response to a keyed request carries your quota, so you never have to guess how close you are:

Past the limit the API answers 429 and adds Retry-After, the same number of seconds, so a client that backs off on that header waits exactly as long as it needs to rather than retrying into a wall. Nothing is charged for a refused request and the counter still rolls at midnight UTC.

Reading X-RateLimit-Remaining is cheaper than handling the 429: a job that pages through results can stop itself and resume tomorrow instead of failing halfway.