OpenBB-finance/OpenBB · error · OpenBBError

Unexpected response format. Expected a dictionary, got {type

Error message

Unexpected response format. Expected a dictionary, got {type(response)}

What it means

Raised in FredSearchFetcher.aextract_data (openbb_fred/models/search.py:249) when the parsed FRED response is neither an error dict (no 'error_code') nor a result dict (no 'count') - or is not a dict at all, e.g. a list or string. This is a defensive guard against an unexpected response shape: the helper fred_get returned something the search extractor does not know how to interpret, so it refuses to guess.

Source

Thrown at openbb_platform/providers/fred/openbb_fred/models/search.py:249

            ["search_text", "limit"] if query.release_id is not None else ["limit"]
        )

        if query.release_id is not None and query.order_by == "search_rank":
            query.order_by = None  # type: ignore

        querystring = get_querystring(query.model_dump(), exclude).replace(" ", "%20")
        url = url + querystring + f"&file_type=json&api_key={api_key}"
        response = await fred_get(url)

        if isinstance(response, dict) and "error_code" in response:
            raise OpenBBError(
                f"FRED API Error -> Status Code: {response['error_code']} -> {response.get('error_message', '')}"
            )

        if isinstance(response, dict) and "count" in response:
            results = response.get("seriess", [])
            return results
        raise OpenBBError(
            f"Unexpected response format. Expected a dictionary, got {type(response)}"
        )

    @staticmethod
    def transform_data(
        query: FredSearchQueryParams, data: list[dict], **kwargs: Any
    ) -> list[FredSearchData]:
        """Transform data."""
        # pylint: disable=import-outside-toplevel
        from numpy import nan
        from pandas import DataFrame, Series

        if not data:
            raise EmptyDataError("The request was returned empty.")

        df = DataFrame(data)

        if query.search_type == "release" and query.release_id is None:

View on GitHub (pinned to 3e071fcc2c)

Solutions

1. Inspect the raw response by curling the same URL with your key to see what FRED actually returns.
2. Update the openbb-fred provider package (pip install -U openbb-fred) in case the parser was fixed for a new envelope.
3. Remove intercepting proxies/rewrites for api.stlouisfed.org.
4. If the response is legitimately a new format, open an issue on the OpenBB GitHub with the (redacted) payload.

def is_search_results_payload(payload: object) -> bool:
    """True when the payload is a dict with the expected 'count'/'seriess' keys."""
    return isinstance(payload, dict) and 'count' in payload

from openbb_core.app.model.abstract.error import OpenBBError

try:
    res = obb.economy.fred.search(query=q)
except OpenBBError as e:
    if 'Unexpected response format' in str(e):
        # environment/proxy problem - surface it, do not retry blindly
        raise RuntimeError('FRED search got an unexpected payload; check proxies/network') from e
    raise

When it happens

Trigger: A proxy or middleware returning HTML/text that got parsed into a string; FRED changing its JSON envelope in a way that drops 'count'; a truncated response from network interruption being parsed to a non-dict.

Common situations: Corporate proxies intercepting api.stlouisfed.org; pinned old openbb-fred package against a changed FRED API; flaky connections behind NAT/VPNs.

Related errors

• {str(e) or 'FRED request failed ({type(e).__name__}).'}
• Unexpected result while retrieving the list of releases from
• {str(e) or 'FRED request failed ({type(e).__name__}).'}
• Failed to parse XML response: {url} -> {e}
• Method must be GET or POST

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