UK Data AtlasAPI

Using the API

Errors

When something goes wrong, the API tells you what happened and why, in the same format every time. Many errors are deliberate: the API would rather refuse than hand you a number that looks right but isn't.

What an error looks like

Errors follow the Problem Details standard (RFC 9457) and are always sent as application/problem+json, whatever format you asked for:

Error
{
  "type": "https://api.ukdataatlas.com/problems/operation-not-supported",
  "title": "Operation Not Supported",
  "status": 422,
  "detail": "This measure is a median and cannot be combined over areas.",
  "code": "aggregation_not_supported"
}

title and detail are written for people. code is stable, so branch on that in your code. Some errors add more, like the choices for an ambiguous place name.

Status codes

StatusWhat it means
200 OKIt worked.
204 No ContentIt worked, and there's nothing to send, such as a map tile with no areas in it.
304 Not ModifiedYour cached copy is still current. See Caching.
400 Bad RequestA parameter is missing or malformed. detail says which.
404 Not FoundNothing matches what you asked for, such as an unknown measure or area code.
409 ConflictWhat you asked for is ambiguous. The response lists the choices.
410 GoneThat Atlas release is no longer served.
422 UnprocessableThe request is clear, but answering it would be misleading, so the API declines.
414 URI Too LongThe request target is longer than the server accepts. Send fewer codes, or page the request.
429 Too Many RequestsYou've spent your requests for now. Retry-After says how many seconds to wait. See Rate limits.
500 Server ErrorThe route failed unexpectedly. The response carries a requestId; quote it if you report the failure.
503 UnavailableThe data isn't ready yet. Try again shortly.

Error codes

These are the code values you can rely on, with what to do about each:

CodeWhat happenedWhat to do
unsupported_geography404That geography isn't available, or its areas aren't compiled.Check the spelling against List geographies.
unknown_release404The geography exists, but has no boundary release with that id.The response's availableReleases lists the ones it has. A release id names its coverage and product as well as its date, such as 2024-12-uk-bgc; latest picks the newest.
area_not_in_release404The boundary release you named doesn't contain that area code.The response's presentIn lists the releases that do hold the code.
aggregation_not_supported422This measure can't be combined that way, like adding up medians or ranks.Check the measure's aggregation with Get a measure, and use individual observations instead.
conversion_not_available422The crosswalk can't convert this data without dropping, splitting or guessing values.Try another crosswalk from List crosswalks, or keep the data on its original areas.
partial_coverage422Some areas a total needs are missing, so no total is given rather than a quietly incomplete one.See where the measure is published with Check a measure's coverage, then choose a period or group of areas it fully covers.
ambiguous_place409The name matches several places that have different answers.Pick one of the choices in the response and pass its place reference.
incompatible_geometry422Not every area code in the data appears in the boundary release you chose.Find a release that fits with Check which boundaries fit.
invalid_format400This endpoint doesn't offer the format you asked for.Use one of the formats listed for the endpoint's format parameter.
invalid_cursor400The cursor wasn't issued by the API, or belongs to a different query.Start again from the first page, and only pass back the nextCursor you were given for the same query.
unknown_query_parameter400This operation doesn't declare the query parameter you sent.Remove the parameter or replace it with the response's optional suggestion.
no_release_for_date404No boundary release covers that date (or that country).The absence field says why. Try a later date or drop country.
ambiguous_release409Several releases from the same month could fit, and they differ in more than coverage.Pick one of the choices in the response and use its release id.

Handling errors

Check the status, then branch on code for the cases you want to handle. Here, asking for a total of median house prices is refused:

const response = await fetch(
  "https://api.ukdataatlas.com/v1/data/house-price-median/aggregate?period=2022&geography=ward&boundaryYear=2020&place=E92000001",
);

if (!response.ok) {
  const problem = await response.json();

  if (problem.code === "aggregation_not_supported") {
    // Show each area's value instead of a total
  }
  throw new Error(`${problem.title}: ${problem.detail}`);
}

A 422 isn't a bug in your code. It usually means there's a better question to ask, and detail points you towards it.