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

Status	When
`400`	The request is understood but cannot be served as asked, e.g. offset above 9500, or cursor combined with sort_by=value. The message names the fix.
`403`	Missing or invalid API key.
`404`	No such endpoint, or no record with that id.
`422`	A parameter is invalid: an unknown city slug, an impossible date, a limit above 500, an unrecognised sort field, or a misspelled parameter name. The message names the parameter and, where there is one, the nearest valid value.
`429`	Rate limit or plan quota exceeded.
`500`	Unexpected server error.
`504`	The query took too long. Narrow it with a municipality or a date range.

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.

Ready to build?Subscribe on RapidAPI to get your key and start calling BuildData in minutes.