Troubleshooting¶

This page lists the most common issues when integrating with the Urban Analytica Solar Lake Enterprise API and how to fix them.

API Base URL

https://ua-api-solar-lake-enterprise.azurewebsites.net

1) 403 Access denied¶

Symptoms¶

Response status is 403
Response body contains something like:
- {"detail":"Access denied"}
- or a similar authorization message

Cause¶

All endpoints require a valid subscription_key query parameter (exact length: 90).

Fix¶

Always pass the key as a query parameter:

curl "https://ua-api-solar-lake-enterprise.azurewebsites.net/building?building_id=01c02e568d94065d29c7fd9e&subscription_key=YOUR_KEY"

If you are using a browser-based client (e.g., Swagger UI / a frontend app), verify that:

The key is included in the request URL
The key has not expired / been revoked

2) 422 Validation Error¶

Symptoms¶

Response status is 422
The response contains a detail list with validation errors (Pydantic-style)

Common causes¶

Missing required query parameters (building_id, postcode, ags, …)
Wrong types (string vs number)
Out-of-range values (e.g., invalid lat/lon range)
Request body does not match the schema (POST endpoints)
Invalid filter operator or invalid filter shape

Fix¶

Check the request against the OpenAPI schema (Swagger UI / openapi.json) and ensure:

Required fields exist
Types match
Coordinate ranges are valid
Filter syntax matches supported operators

3) “No results” / empty responses¶

Symptoms¶

You get returned: 0 in bbox or query endpoints
Batch endpoints return missing_ids / missing_points

Causes¶

The requested object/region truly has no data
You requested a bbox outside supported areas
Your filter is too strict
You requested IDs/points that do not match any building footprint

Fix¶

Start without filters and add them incrementally
Verify coordinates are correct and in WGS84 lon/lat (not swapped)
For batch endpoints, handle missing_ids / missing_points gracefully
For bbox endpoints, increase the bbox slightly to confirm coverage

4) Wrong coordinate order (lon/lat swapped)¶

Symptoms¶

GET /building-coordinates returns no building where you expect one
Bbox endpoints return unrelated areas or empty results

Cause¶

The API uses WGS84 with longitude first, then latitude:

lon ∈ [-180, 180]
lat ∈ [-90, 90]

Note that coordinates inside the supported area (Germany) are only within:

lon ∈ [5, 16]
lat ∈ [46, 56]

Fix¶

Make sure you send lon, lat (not lat, lon).

Correct:

curl "https://ua-api-solar-lake-enterprise.azurewebsites.net/building-coordinates?lon=7.1202&lat=51.481&subscription_key=YOUR_KEY"

5) Map viewport endpoints return “slightly outside” features¶

Symptoms¶

Some returned objects are just outside your bbox

Cause¶

Bounding box queries are optimized for performance and may include a small number of objects slightly outside the requested bbox.

Fix¶

If your UI requires strict clipping:

Clip on the client side (e.g., check point-in-bbox for building centroids)
Or apply geometric clipping in your map rendering pipeline

6) Too much data / slow responses¶

Symptoms¶

Slow requests
Large payloads
Browser UI becomes sluggish

Causes¶

Requesting full documents (including geometry + roof arrays) when not needed
Using very large limit values
Using offset pagination (skip) for deep pages
Using a very large bbox at high zoom levels
Requesting huge amounts of records at once

Fixes¶

A) Always use projection for POST endpoints¶

Use options.select to request only the fields you need:

{
  "options": {
    "select": ["building_id", "roof_area", "pv", "sales_opportunity_score"],
    "limit": 5000
  }
}

B) Prefer cursor pagination for bulk exports¶

For POST /query/buildings, use after_building_id instead of large skip offsets.

C) Reduce viewport payload¶

For buildings: load fewer fields
For aggregates: use H3 at a suitable resolution, or let the API auto-select

D) Split requests by ID into batches¶

Lookup endpoints (e.g., /buildings, /h3s) do not support pagination. If you need to process very large ID lists, split them into smaller batches client-side.

7) Incremental viewport loading duplicates¶

Symptoms¶

Your client loads the same objects again while panning/zooming
You see duplicate features on the map

Cause¶

Viewport requests overlap. Without exclusion, the backend will re-send data for the overlapping area.

Fix¶

Use the advanced POST bbox endpoints with exclude:

exclude.exclude_bboxes: subtract areas already loaded by the client
exclude.exclude_ids: exclude already-known IDs

Example:

{
  "bbox": { "min_lon": 11.5, "min_lat": 48.1, "max_lon": 11.51, "max_lat": 48.11 },
  "exclude": {
    "exclude_bboxes": [
      { "min_lon": 11.505, "min_lat": 48.105, "max_lon": 11.506, "max_lat": 48.106 }
    ]
  },
  "options": {
    "select": ["building_id", "roof_area"],
    "limit": 5000
  }
}

8) CORS errors (browser frontend)¶

Symptoms¶

Browser console shows CORS errors like:
- “Blocked by CORS policy”
- Preflight request failing

Cause¶

Browsers enforce CORS. The API may only allow requests from configured origins.

Fix¶

Contact Urban Analytica support

9) Timeouts / gateway errors (e.g., 502/504)¶

Symptoms¶

Intermittent 502/504
Requests fail for large regions / large limits

Causes¶

Very large export requests
Excessive response size
Too many partitions/shards touched at once (bulk region selectors)

Fix¶

Reduce limit
Use projection (options.select)
Split exports into smaller region batches (e.g., chunk postcodes/AGS lists)
Prefer cursor paging for bulk extraction

10) “Filter not supported” / filter field rejected¶

Symptoms¶

422 error when using a filter field that “should exist”
Filter operators rejected

Cause¶

For safety and performance, the API only allows filtering on an allowlisted set of fields per endpoint type.

Fix¶

Validate operator usage: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin
Start with a simple filter and add fields incrementally
If you need a new filter field, contact Urban Analytica support to discuss adding it safely

11) Empty Cells Not Returned¶

If you request empty H3 cells using:

include_empty_cells = "ids"

or

include_empty_cells = "geometries"

but the response does not contain them, check the following:

Pagination

Empty cells may be suppressed when pagination parameters make the result ambiguous.

For example:

skip > 0
limit smaller than the total number of cells in the bounding box

In this case the response will include:

"empty_cells_suppressed": true

To receive empty cells, request the full viewport without pagination.

12) Batch coordinate lookup does not return all points¶

Symptoms¶

Some input coordinates are missing in results
missing_points is populated

Cause¶

The endpoint resolves buildings via point-in-polygon matching.

Points may be missing if:

They lie outside Germany
They do not intersect any building footprint
Coordinates are slightly off (e.g., wrong geocoding)

Fix¶

Always handle missing_points in batch workflows
Do not assume requested == returned
Use input_point in items to reliably merge results

The endpoint will not fail for invalid coordinates. All inputs are processed.

Still stuck?¶

When reporting an issue, include:

Endpoint + method (GET/POST)
Full URL (without exposing your key publicly)
Request body (for POST)
Response status code + response body

This makes it much faster to diagnose the problem.