OpenBB-finance/OpenBB · error · OpenBBError

Unexpected response format. Expected a dictionary, got

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.

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

• ).'}
• Failed to parse XML response
• ).'}
• Unexpected result while retrieving the list of releases…
• A query is required for search_type 'full_text' or…

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

Appendix: 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)