OpenBB-finance/OpenBB · error · OpenBBError

FRED API Error -> Status Code: {response['error_code']} -> {

Error message

FRED API Error -> Status Code: {response['error_code']} -> {response.get('error_message', '')}

What it means

Raised in FredSearchFetcher.aextract_data (openbb_fred/models/search.py:242) when the FRED response is a dict containing 'error_code' - the API's structured error envelope. The message surfaces FRED's own status code and message verbatim. Common FRED codes here: 400 (invalid argument or malformed request), 401/402 (invalid or missing API key), 429 (exceeded 50 requests/minute), 500 (FRED server error).

Source

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

        url = (
            "https://api.stlouisfed.org/fred/release/series?"
            if query.release_id is not None
            else "https://api.stlouisfed.org/fred/series/search?"
        )

        exclude = (
            ["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

View on GitHub (pinned to 3e071fcc2c)

Solutions

1. Read the embedded error_message - it names the exact offending parameter.
2. For 40x api_key errors, set a valid key via obb.user.credentials.fred_api_key.
3. For 429, throttle to under 50 requests/minute and retry with backoff.
4. For 400, simplify parameters (drop order_by, fix tag syntax) and retry.

Example fix

# before - unthrottled fan-out
await asyncio.gather(*[obb.economy.fred.search(query=q) for q in queries])

# after - serialize to respect the 50 req/min limit
for q in queries:
    try:
        res = await obb.economy.fred.search(query=q)
    except OpenBBError as e:
        if '429' in str(e):
            await asyncio.sleep(60)
            res = await obb.economy.fred.search(query=q)

def is_fred_api_error(payload: dict) -> bool:
    """True when FRED returned its structured error envelope."""
    return isinstance(payload, dict) and 'error_code' in payload

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

def search_with_backoff(**params):
    for delay in (0, 60, 120):
        if delay:
            time.sleep(delay)
        try:
            return obb.economy.fred.search(**params)
        except OpenBBError as e:
            msg = str(e)
            if '429' in msg and delay != 120:
                continue  # rate limited -> backoff and retry
            raise

When it happens

Trigger: Invalid fred_api_key -> 'api_key' errors (40x); limit/offset beyond result count or bad order_by -> 400; bursting parallel searches -> 429 rate limit; malformed tag expressions from tag_names/exclude_tag_names.

Common situations: Unconfigured or expired API key; batch scripts fanning out many fred_search calls concurrently; passing order_by='search_rank' together with a release_id in older versions (the code now strips it, but hand-built queries may still hit 400).

Related errors

• The request was returned empty.
• Failed to fetch data from FRED API: {e}
• No data found for the item and region combination. You may a
• Unexpected result while retrieving the list of releases from
• There was an error with the request and it was returned empt

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