OpenBB-finance/OpenBB · error · HTTPException

Bill URL is required. Please provide a valid bill URL or num

Error message

Bill URL is required. Please provide a valid bill URL or number.

What it means

HTTPException(500) from the OpenBB congress.gov FastAPI router when a bill-text-choices endpoint is called with an empty bill_url outside workspace mode. Workspace mode returns a friendly placeholder list instead; a plain API call gets a hard 500 because there is no bill to enumerate documents for. Note the 500 status is arguably wrong for a client-input problem — expect it to feel like a server error in traces.

Source

Thrown at openbb_platform/providers/congress_gov/openbb_congress_gov/router/congress_gov_router.py:163

    Returns
    -------
    list[dict]
        Returns a list of dictionaries with 'label' and 'value' keys, when `is_workspace` is True.
        Otherwise, returns the 'text' object from the Congress.gov API response.
    """
    # pylint: disable=import-outside-toplevel
    from openbb_congress_gov.utils.helpers import get_bill_text_choices

    if not bill_url and is_workspace is True:
        return [
            {
                "label": "Enter a valid bill URL to view available documents.",
                "value": "",
            }
        ]

    if not bill_url:
        raise HTTPException(
            status_code=500,
            detail="Bill URL is required. Please provide a valid bill URL or number.",
        )

    if (bill_url.startswith("/") and bill_url[1].isdigit()) or bill_url[0].isdigit():
        # If the bill_url is a number, assume it is a congress number and append the base URL
        base_url = "https://api.congress.gov/v3/bill"
        bill_url = (
            base_url + bill_url
            if bill_url.startswith("/")
            else (base_url + "/" + bill_url if bill_url[0].isdigit() else bill_url)
        ) + "?format=json"

    return await get_bill_text_choices(bill_url=bill_url, is_workspace=is_workspace)


@router.command(
    model="CongressBillInfo",

View on GitHub (pinned to 3e071fcc2c)

Solutions

Always pass bill_url, either a full v3 URL or a 'congress/type/number' shorthand (e.g. '119/hr/1') that the router expands.
In frontend code, disable the submit action until the field is non-empty.
If you rely on workspace UX behavior, pass is_workspace=true to get the placeholder payload instead of the 500.

Example fix

# before
obb.congress.gov_router.bill_text_choices(bill_url='')

# after
obb.congress.gov_router.bill_text_choices(bill_url='119/hr/1')

Defensive patterns

Strategy: validation

Validate before calling

if not bill_url or not bill_url.strip():
    raise ValueError('bill_url is required (e.g. "119/hr/1" or a full v3 URL)')

Type guard

import re

def is_bill_shorthand(v: str) -> bool:
    return bool(re.fullmatch(r'\d{2,3}/(hr|s|hjres|sjres|hconres|sconres|hres|sres)/\d+', v))

Try / catch

from fastapi import HTTPException

try:
    choices = await get_bill_text_choices(bill_url=bill_url)
except HTTPException as e:
    if e.status_code == 500 and 'Bill URL is required' in e.detail:
        return render_empty_state()
    raise

Prevention

Disable submit until bill_url is non-empty in frontends.
Prefer the compact shorthand to avoid URL-format mistakes.
Pass is_workspace=true when you want placeholder payloads for empty input.

When it happens

Trigger: GET /api/v1/congress_gov/bill_text_choices with no bill_url query param (and is_workspace false/absent); a UI bug clearing the field before submission.

Common situations: Custom frontends calling the router directly; curl/python tests omitting the required param; form state bugs that submit empty strings.

Related errors

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