OpenBB-finance/OpenBB · error · OpenBBError

Unexpected response format when fetching constraints {datafl

Error message

Unexpected response format when fetching constraints {dataflow_id}: {e} -> {url}

What it means

Raised when the SDMX availability/constraints endpoint returns HTTP success or a response whose body is not valid JSON (response.json() raises json.JSONDecodeError). The message includes the JSON error and the exact URL queried. Typical shapes: an HTML error page served with 200, an empty body from a gateway, or an XML SDMX error delivered to a request that declared Accept: application/json.

Source

Thrown at openbb_platform/providers/imf/openbb_imf/utils/metadata.py:746

        query_params.update(c_params)

        query_params = {k: v for k, v in query_params.items() if v is not None}
        url = (
            base_url + "?" + "&".join(f"{k}={v}" for k, v in query_params.items())
            if query_params
            else base_url
        )
        json_response: dict = {}
        try:
            headers = {
                "Accept": "application/json",
                "User-Agent": "Open Data Platform - IMF Metadata Utility",
            }
            response = make_request(url, headers=headers)
            response.raise_for_status()
            json_response = response.json()
        except json.JSONDecodeError as e:
            raise OpenBBError(
                f"Unexpected response format when fetching constraints {dataflow_id}: {e}"
                + f" -> {url}"
            ) from None
        except RequestException as e:
            raise OpenBBError(
                f"An error occurred while fetching constraints {dataflow_id}: {e} -> {url}"
            ) from None

        extracted_values: dict = {}
        json_data = json_response.get("data", {})
        data_constraints = json_data.get("dataConstraints", [])

        for constraint in data_constraints:
            for region in constraint.get("cubeRegions", []):
                for kv in region.get("keyValues", []):
                    dim_id = kv.get("id")
                    if dim_id:
                        if dim_id not in extracted_values:

View on GitHub (pinned to 3e071fcc2c)

Solutions

1. Retry after a short delay — transient gateway pages usually clear.
2. Reduce the size of the constraint key (fewer indicator codes per call) to avoid URL-length-triggered error pages; the module already limits keys to depth 0-1 codes for this reason.
3. If persistent, update openbb-imf (the endpoint or response shape may have changed) and inspect the URL from the message directly in a browser/curl to see what is actually returned.

Example fix

# before
constraints = meta.fetch_dataflow_constraints('IMTS', key='A.US.TXG_FOB_USD+TXG_CIF_USD+...' )  # 50-code key -> long URL -> HTML error page

# after (chunked keys)
for chunk in chunkify(indicator_codes, 5):
    constraints = meta.fetch_dataflow_constraints('IMTS', key='.'.join(['A', 'US', '+'.join(chunk)]))

# keep constraint keys short to avoid URL-length error pages
if len(key) > 1500:
    raise ValueError('Constraint key too long; split indicator codes into smaller calls.')

import asyncio
for attempt in range(3):
    try:
        constraints = meta.fetch_dataflow_constraints(df_id, **kwargs)
        break
    except OpenBBError as e:
        if 'Unexpected response format' not in str(e) or attempt == 2:
            raise
        await asyncio.sleep(2 ** attempt)

When it happens

Trigger: IMF API gateway briefly returning HTML maintenance pages; requesting a constraints key so long the server truncates it and responds with an HTML 414/400-style page; XML error envelopes on malformed keys; proxy/CDN interstitials.

Common situations: Very large indicator selections producing long availability URLs; transient gateway issues; corporate proxies injecting HTML; API contract changes after IMF portal updates.

Related errors

• An error occurred during the HTTP request: {url} -> {e} -> {
• Failed to fetch data for port {port_code}: {e} -> {e.args}
• Error fetching port data: {result} -> {result.args[0]}
• Agency ID not found for dataflow '{dataflow_id}'.
• An error occurred while fetching constraints {dataflow_id}:

AI-assisted analysis of OpenBB-finance/OpenBB@3e071fcc2c (2026-08-14). Data as JSON: /api/errors/ae9adf7ad18b2fde. Report an issue: GitHub.