What does HTTP 429 mean from the Homedata API?

HTTP 429 means a request limit has been exceeded. The error body includes the error code rate_limit_exceeded. Check the X-RateLimit-Remaining header to monitor usage.

What format do Homedata API errors use?

All errors return JSON with an error object containing code (machine-readable, lowercase_snake_case) and message (human-readable). Example: {"error": {"code": "not_found", "message": "No property found with UPRN 999999999999"}}

What HTTP status code does the API return for an invalid API key?

HTTP 401 Unauthorized. The error code will be invalid_api_key. Check that you are using the Api-Key prefix in the Authorization header, not Bearer.

Error Handling

Every error response follows a consistent JSON format. Use HTTP status codes to handle errors programmatically.

Error format

All error responses return JSON with a consistent structure:

Error Response

{
  "error": {
    "code": "not_found",
    "message": "No property found with UPRN 999999999999"
  }
}

Field	Type	Description
error	object	Error detail object (always present on non-2xx responses)
error.code	string	Machine-readable error code (`lowercase_snake_case`). Safe to switch on in code.
error.message	string	Human-readable description. May change — don't match on this programmatically.

HTTP status codes

200

OK

Request succeeded. Response body contains the requested data.

400

Bad Request

Missing or invalid parameters. Check the message field for specifics.

{"error": {"code": "bad_request", "message": "Missing required parameter: postcode"}}

401

Unauthorized

Missing or invalid API key. Make sure you're using the Authorization: Api-Key header.

{"error": {"code": "authentication_required", "message": "Valid API key required"}}

403

Forbidden

API key is valid but doesn't have permission for this resource. May indicate a revoked key or scope restriction.

404

Not Found

The requested resource doesn't exist. For property endpoints, this means no data for that UPRN.

{"error": {"code": "not_found", "message": "No property found with UPRN 999999999999"}}

429

Rate Limit Exceeded

A request limit has been reached. Check the X-RateLimit-* headers.

{"error": {"code": "rate_limit_exceeded", "message": "Request limit reached."}}

500

Internal Server Error

Something went wrong on our side. These are rare and we're alerted automatically. If persistent, please contact us.

504

Gateway Timeout

Request took too long to process. Retry with exponential backoff. If frequent, the endpoint may be under heavy load.

Error codes

All error codes use lowercase_snake_case. Switch on error.code to handle errors programmatically.

Code	Status	Description
authentication_required	401	Missing or invalid API key
forbidden	403	API key is valid but revoked or lacks permission
endpoint_not_allowed	403	API key not authorised for this endpoint.
not_found	404	No data for the requested resource (UPRN, postcode, URN, etc.)
invalid_params	422	Missing or invalid query parameters
invalid_uprn	422	UPRN format is invalid (must be 8–12 digits)
invalid_postcode	422	Postcode doesn't match UK format
missing_postcode	422	Required postcode parameter not provided
rate_limit_exceeded	429	Request rate limit reached
service_unavailable	503	Data source temporarily unavailable. Retry with backoff.

Handling errors in code

# Python — switch on error.code
response = requests.get(url, headers=headers)

if not response.ok:
    err = response.json().get("error", {})
    code = err.get("code")

    if code == "authentication_required":
        raise AuthError(err["message"])
    elif code == "rate_limit_exceeded":
        time.sleep(60)  # back off
    elif code == "not_found":
        return None
    else:
        raise ApiError(f"{code}: {err.get('message')}")

Rate limiting

Every authenticated response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Request allowance for the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the limit resets

Best practice: handle 429 gracefully

# Python — retry with backoff
import time

def api_call(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
            continue
        return response.json()
    raise Exception("Rate limit exceeded after retries")

API Reference → ← Getting Started

Integrate into your own product

Free to start

Homedata API Scientific, granular measurements

Homedata API error responses follow a consistent JSON format with machine-readable codes across all 38 endpoints — enabling reliable error handling in any language without parsing free-text messages.

Structured as JSON · queryable by UPRN or postcode · ready to embed in any application

Exact measurements

Real values — distances, concentrations, counts — not rounded ratings

29M+ UK properties

Every address queryable by UPRN or postcode

REST API

JSON responses, OpenAPI docs, sandbox — first call in under 5 minutes

Get your free API key View pricing Try a live API call →

Free tier: 100 API calls/month across all endpoints, no credit card required. Paid plans from £29/month for production use. Compare plans →

Sources

[1] MDN: HTTP response status codes