Build reliably

Errors and pagination

Handle predictable JSON errors, bounded result sets and authority-specific gaps without silently changing the meaning of a result.

Error shape

{
  "error": "APPLICATION_NOT_FOUND",
  "message": "Planning application not found."
}

Validation failures use a machine-readable error code and a human-readable message. Missing single records return HTTP 404. Invalid filters or identifiers return HTTP 400.

Council references are not unique

Distinct applications can share a council reference. HomeRadar never chooses the newest matching record to resolve this ambiguity. HTTP 409 returns:

{
  "error": "AMBIGUOUS_REFERENCE",
  "message": "Multiple released applications match this council and reference. Use an application ID."
}

Use the stable HomeRadar application ID from a permitted search result with /applications/:id. Repeating the same reference request does not resolve the conflict. Matching considers only records permitted by the release gate; the error does not expose restricted records or candidate details.

Pagination

{
  "data": [],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 0
  }
}

List endpoints default to 25 records per page and cap limit at 100. Nearby lookup is bounded by limit rather than page-based pagination.