Errors & Status Codes
PropertyAPI uses standard HTTP status codes and a consistent error object, so failures are predictable and easy to handle programmatically.
HTTP status codes
| Code | Meaning |
|---|---|
200 | Success |
401 | Unauthorized — authentication failed or the API key is missing/invalid |
404 | Not Found — the property or resource does not exist |
422 | Unprocessable Entity — request validation failed (e.g. bad UPRN or postcode) |
429 | Too Many Requests — rate limit exceeded |
Error response
Errors return an ErrorResponse object with a single detail message:
{ "detail": "Unauthorized - Invalid authentication credentials" }More examples:
{ "detail": "Property with UPRN 100023336956 not found" }{ "detail": "Invalid UK postcode format" }ErrorResponseERROR
detail
Human-readable description of the error.
One legacy exception
Most endpoints use the { "detail": "..." } shape. The Market Event History endpoint's 404 is the exception — it returns the legacy envelope:
{ "success": false, "error": "Property event history not found", "version": "2.0" }
Handling errors well
Recommended pattern
Check the HTTP status code first, then read error.detail for a message to display or log. For 429, back off and retry after a short delay, and batch or cache where possible during large-scale enrichment runs.