tiangolo/fastapi · error · HTTPException

You can only update the item: plumbus

Error message

You can only update the item: plumbus

What it means

Raised by PUT /items/{item_id} when item_id is not exactly "plumbus", returning HTTP 403 Forbidden. It is a business-rule restriction: only the plumbus item may be updated. The route declares responses={403} documenting the case.

Source

Thrown at docs_src/bigger_applications/app_an_py310/routers/items.py:35

async def read_items():
    return fake_items_db


@router.get("/{item_id}")
async def read_item(item_id: str):
    if item_id not in fake_items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"name": fake_items_db[item_id]["name"], "item_id": item_id}


@router.put(
    "/{item_id}",
    tags=["custom"],
    responses={403: {"description": "Operation forbidden"}},
)
async def update_item(item_id: str):
    if item_id != "plumbus":
        raise HTTPException(
            status_code=403, detail="You can only update the item: plumbus"
        )
    return {"item_id": item_id, "name": "The great Plumbus"}

View on GitHub (pinned to 42a41db11f)

Solutions

1. Only call PUT /items/plumbus.
2. Read the route's documented 403 response and branch on it.
3. If broader updates are needed, extend the handler rather than bypassing the guard.

Example fix

# before
client.put("/items/gun", headers=auth)
# after
client.put("/items/plumbus", headers=auth)

# Only attempt to update the allowed item
if item_id == "plumbus":
    client.put(f"/items/{item_id}", headers=auth)

def is_updatable(item_id: str) -> bool:
    return item_id == "plumbus"

resp = client.put(f"/items/{item_id}", headers=auth)
if resp.status_code == 403:
    # this item cannot be updated
    ...

When it happens

Trigger: PUT /items/{item_id} with any item_id other than "plumbus" (e.g. PUT /items/gun).

Common situations: Attempting to update a locked/read-only resource; generic update loops that target all ids; misunderstanding that only one item is mutable.

Related errors

• Owner error: {e}
• {username}
• Owner error: {e}
• {username}
• Not authorized

AI-assisted analysis of tiangolo/fastapi@42a41db11f (2026-08-04). Data as JSON: /data/errors/21ab48034f47e139.json. Report an issue: GitHub.