OpenBB-finance/OpenBB · error · OpenBBError

Expecting a list of dictionaries and received a dictionary.

Error message

Expecting a list of dictionaries and received a dictionary.

What it means

parse_context expects a list of series dictionaries (one per requested ticker) but raises OpenBBError when the response is a single dict. The EconDB series API returns a JSON object (not a list) in error conditions — e.g. an error payload keyed by 'error'/'detail' — so this message usually masks an upstream API error such as a bad token, unknown ticker, or rate limit.

Source

Thrown at openbb_platform/providers/econdb/openbb_econdb/utils/helpers.py:528

            try:
                response = await amake_requests(urls, session=session)
            finally:
                await session.close()
    else:
        response = await amake_requests(urls)
    return response


def parse_context(  # pylint: disable=R0912, R0914, R0915
    response: list[dict], latest: bool = False, with_metadata: bool = False
) -> DataFrame | tuple[DataFrame, dict]:
    """Parse the output from `get_context()`, and optionally return the metadata."""
    metadata = {}
    results = DataFrame()
    if response is None:
        raise OpenBBError("No data was in the response")
    if not isinstance(response, list):
        raise OpenBBError("Expecting a list of dictionaries and received a dictionary.")
    for item in response:
        symbol = item.get("id", "")
        _symbol = symbol.split("~")[0].replace("19", "")
        temp_unit = ""
        temp_meta = item.get("td", {})
        temp_data = item.get("dataarray", [])
        temp_transform = symbol.split("~")[1] if "~" in symbol else ""
        temp_country = item.get("geography", {}).get("name", "")
        temp_country = temp_country.replace(" (19 countries)", "")
        # We need the metadata to process the results.
        if temp_meta:
            temp_unit = temp_meta.get("units", "")
            temp_scale = temp_meta.get("scale", "")
            if temp_transform:
                if temp_transform in ["TOYA", "TPOP", "TPGP"]:
                    temp_unit = "Percent"
                if temp_transform == "TUSD":
                    temp_unit = "USD"

View on GitHub (pinned to 3e071fcc2c)

Solutions

Inspect the raw response from https://www.econdb.com/api/series/ for your URL to see the dict error body and its message.
Refresh credentials: set your own econdb_api_key, or clear the token cache so create_token runs again.
Re-validate ticker symbols and their transform suffixes.
Reduce request frequency and retry after limits reset.

Defensive patterns

Strategy: type-guard

Validate before calling

import httpx
r = httpx.get(f'https://www.econdb.com/api/series/?ticker=%5B{ticker}%5D&format=json&token={token}')
body = r.json()
if isinstance(body, dict):
    raise RuntimeError(f'econdb returned an error object: {body}')

Type guard

def is_context_response(x) -> bool:
    """Type guard: parse_context requires list[dict]; a dict means an API error payload."""
    return isinstance(x, list) and not isinstance(x, dict)

Try / catch

from openbb_core.app.model.obbject import OpenBBError
try:
    df = parse_context(response)
except OpenBBError as e:
    if 'Expecting a list' in str(e):
        # response is actually an error dict - inspect it for 'error'/'detail'
        logger.error(f'econdb API error body: {response}')
    raise

Prevention

Inspect dict-shaped responses - they carry the real API error (bad token, unknown ticker, throttle).
Refresh the token / clear cache when this appears after working before.
Log the raw body alongside the exception for diagnosis.

When it happens

Trigger: An econdb get_context call where the API responds with a dict-shaped error document: invalid token in the URL, removed tickers, or throttling — the fetch succeeds (HTTP 200-ish) but the body shape betrays the error.

Common situations: Expired temp token cached and reused; ticker renamed upstream; heavy usage tripping API limits that return structured errors with 200 status.

Related errors

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