Errors and Retries

Check HTTP status before reading a successful series response. A valid request with no observations is different from an invalid selector, denied access or an unavailable release.

Structured Service Errors

json

{
  "request_id": "data_example_invalid_dates",
  "error": {
    "code": "invalid_parameter",
    "message": "from must be on or before to.",
    "field": "from"
  }
}

This is an illustrative error. Real request IDs are generated per request. field is included when the service can identify an offending parameter, but is not guaranteed on every error. The X-Request-ID response header identifies the same request when the service handled it.

Error Reference

HTTP	Code	Typical cause	Action
400	`duplicate_parameter`	A query key appears more than once.	Send each parameter once. Use a comma-separated `metrics` value rather than repeated keys.
400	`unknown_parameter`	Unsupported selector, or parameters on the current-release route.	Remove parameters not allowed by that endpoint/dataset.
400	`invalid_parameter`	Unsupported query on catalogue/areas, where only optional `release_id` is accepted.	Use the support-route contract.
400	`invalid_cursor`	Expired, altered, wrong-identity/family or invalid-release cursor; cursor on coverage.	Restart or use the correct unaltered continuation.
400	`cursor_query_mismatch`	Filters or page size changed during paging.	Continue with the token alone, or start a new selection.
401	`authentication_required` / `invalid_api_key`	Missing or invalid credentials at the relevant authentication boundary.	Supply a valid authorised key.
403	`insufficient_scope`	Key cannot access the selected family.	Obtain the appropriate family access.
403	`product_not_entitled`	At least one selected/default metric is outside the plan.	Choose a permitted subset or change access.
404	`unknown_family`	Family is not `markets` or `rates` on a matched family route.	Correct the path.
404	`unknown_dataset`	Dataset ID is not recognised in that family.	Read the family catalogue.
404	`unknown_area`	A syntactically valid LAD code is absent from this release.	Read the release's areas list.
404	`unknown_release`	Requested retained release is unavailable.	Correct the ID; do not silently substitute current when reproducing analysis.
422	`missing_parameter`	Required initial selector absent or empty.	Supply the dataset's minimum selectors.
422	`invalid_parameter`	Invalid date/range, metric, enum, integer, type/bedroom combination or unsupported node.	Correct the named field.
503	`no_accepted_release`	No current usable family release is configured.	Retry later; preserve previously accepted application data.
503	`release_not_accepted`	The selected release is not approved for serving.	Do not treat the unavailable release as published. Contact support if persistent.
503	`release_integrity_error`	Missing, corrupt, changed or inconsistent serving data.	Retry with backoff; report request ID if persistent. Never convert to empty/zero data.
503	`entitlements_not_configured`	Service access configuration unavailable.	Retry later or report the request ID.

Some package checks happen at service start rather than inside an HTTP request; their failure can surface as general service unavailability. The table describes service error meanings, not a guarantee that every infrastructure failure has this exact envelope.

Unknown routes and unsupported HTTP methods can use the framework's 404/405 response. Authentication, throttling or network failures at the public gateway can also return a different JSON body or a non-JSON response. Do not parse all errors as if they were successful Data Bank envelopes.

What Is Not an Error

A valid date range outside retained history returns 200 with empty observations and availability metadata.
An admitted dataset may include an unavailable metric while other requested metrics are present.
A ratio with a zero denominator can return a null value and reason.
The latest curve can lack a requested node that exists in older retained snapshots.

These cases require presentation logic, not blind retries. A 200 does not mean every measure contains a usable number.

Retry Policy

GET requests are read-only, so retrying does not create a valuation job or duplicate a transaction. Nevertheless, excessive retries consume capacity and can worsen an outage.

Retry transient network errors and selected 5xx responses with bounded exponential backoff and jitter. Respect Retry-After when supplied. If 429 is returned, reduce request rate and follow your account's usage policy. Quotas are account-specific; do not rely on an undocumented quota endpoint or rate-limit header.

Do not automatically retry 400, 401, 403, 404 or 422 until their cause is corrected. A timed-out latest request can resolve to a newer release when retried; pin a known retained release if that distinction matters. Cursor continuations remain pinned.

Reporting an Issue

Provide request ID, UTC request time, endpoint, non-secret query parameters, HTTP status and error code. Include the selected release ID where known. Redact API keys, authorization headers and cursors. Do not send customer secrets to diagnose a missing observation.