tiangolo/fastapi · error · HTTPException

X-Token header invalid

Error message

X-Token header invalid

What it means

Non-Annotated variant of error 28: `verify_token` (`x_token: str = Header()`) raises HTTP 400 "X-Token header invalid" when the X-Token header differs from "fake-super-secret-token". Registered as a global dependency, so it gates every route.

Source

Thrown at docs_src/dependencies/tutorial012_py310.py:6

from fastapi import Depends, FastAPI, Header, HTTPException


async def verify_token(x_token: str = Header()):
    if x_token != "fake-super-secret-token":
        raise HTTPException(status_code=400, detail="X-Token header invalid")


async def verify_key(x_key: str = Header()):
    if x_key != "fake-super-secret-key":
        raise HTTPException(status_code=400, detail="X-Key header invalid")
    return x_key


app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])


@app.get("/items/")
async def read_items():
    return [{"item": "Portal Gun"}, {"item": "Plumbus"}]


@app.get("/users/")
async def read_users():

View on GitHub (pinned to 42a41db11f)

Solutions

  1. Send `X-Token: fake-super-secret-token`.
  2. Externalize the expected token to env/config.
  3. Use 401 status for authentication failures.
  4. Document required headers via OpenAPI security.

Example fix

# before
if x_token != "fake-super-secret-token":
    raise HTTPException(status_code=400, detail="X-Token header invalid")

# after
if x_token != settings.expected_token:
    raise HTTPException(status_code=401, detail="Unauthorized")
Defensive patterns

Strategy: validation

Validate before calling

if not headers.get("X-Token") or headers["X-Token"] != EXPECTED_TOKEN:
    raise PermissionError("missing/invalid X-Token")

Type guard

def token_ok(headers: dict) -> bool:
    return headers.get("X-Token") == EXPECTED_TOKEN

Try / catch

r = client.get("/items/", headers=headers)
if r.status_code == 400 and r.json().get("detail") == "X-Token header invalid":
    ...

Prevention

When it happens

Trigger: Any request missing or mismatching the X-Token header on the tutorial012_py310 app.

Common situations: Header omitted; wrong value; case-sensitivity mistakes; secret rotation.

Related errors

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