OpenBB-finance/OpenBB · error · HTTPException

Amendment URL is required. Please provide a valid amendment

Error message

Amendment URL is required. Please provide a valid amendment shorthand (e.g., '119/hamdt/2').

What it means

HTTPException(500) from the congress.gov router when the amendment-text-choices endpoint is called without amendment_url and not in workspace mode. Same shape as the bill variant: workspace callers get a placeholder list, direct API callers get a 500 with guidance to use the shorthand form like '119/hamdt/2'.

Source

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

) -> list:
    """Get document choices for a specific amendment.

    This function is used by the Congressional Amendment Viewer widget, in OpenBB Workspace,
    to populate document choices for the selected amendment.
    """
    # pylint: disable=import-outside-toplevel
    from openbb_congress_gov.utils.helpers import get_amendment_text_choices

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

    if not amendment_url:
        raise HTTPException(
            status_code=500,
            detail="Amendment URL is required. Please provide a valid amendment shorthand (e.g., '119/hamdt/2').",
        )

    return await get_amendment_text_choices(
        amendment_url=amendment_url, is_workspace=is_workspace
    )


@router.command(
    model="CongressAmendmentInfo",
    examples=[
        APIEx(
            parameters={
                "provider": "congress_gov",
                "amendment_url": "119/hamdt/2",
            }
        ),

View on GitHub (pinned to 3e071fcc2c)

Solutions

Supply amendment_url in 'congress/amendment-type/number' form (e.g. '119/hamdt/2') or a full v3 URL.
Validate non-empty input on the client before calling.
Pass is_workspace=true if you want the placeholder response for empty input.

Example fix

# before
obb.congress.gov_router.amendment_text_choices(amendment_url='')

# after
obb.congress.gov_router.amendment_text_choices(amendment_url='119/hamdt/2')

Defensive patterns

Strategy: validation

Validate before calling

if not amendment_url or not amendment_url.strip():
    raise ValueError('amendment_url is required, e.g. "119/hamdt/2"')

Type guard

import re

def is_amendment_shorthand(v: str) -> bool:
    return bool(re.fullmatch(r'\d{2,3}/(hamdt|samdt)/\d+', v))

Try / catch

from fastapi import HTTPException

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

Prevention

Make amendment_url mandatory in client forms and generated SDKs.
Use the 'congress/amendment-type/number' shorthand consistently.
Remember this returns HTTP 500, not 400 — match on the detail text when handling it.

When it happens

Trigger: GET amendment_text_choices with no amendment_url; empty-string submissions from a broken form; automated clients that assume the param is optional.

Common situations: Integrations built against the REST API rather than the Python interface; missed required params in generated clients; cleared input fields.

Related errors

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