tiangolo/fastapi · error · HTTPException

X-Token header invalid

Error message

X-Token header invalid

What it means

Identical to error 26 but in the non-Annotated tutorial012_py310.py (uses `x_token: str = Header()` instead of `Annotated[str, Header()]`). Same global dependency verify_token enforces X-Token == 'fake-super-secret-token' on every route, raising HTTPException(400) on mismatch.

Solutions

1. Send X-Token: fake-super-secret-token on every request.
2. Verify the header name maps to the parameter (x_token -> 'X-Token').
3. Move the secret to config/env and share it between server and client.

Example fix

// before
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")
// after
import os
EXPECTED = os.environ["EXPECTED_X_TOKEN"]
async def verify_token(x_token: str = Header()):
    if x_token != EXPECTED:
        raise HTTPException(status_code=400, detail="X-Token header invalid")

headers = {'X-Token': os.environ['X_TOKEN']}
assert headers['X-Token'] == 'fake-super-secret-token'

def has_valid_x_token(headers: dict) -> bool:
    return headers.get('X-Token') == 'fake-super-secret-token'

resp = requests.get(url, headers=headers)
if resp.status_code == 400:
    print('X-Token invalid:', resp.json()['detail'])

When it happens

Trigger: Any request without a valid X-Token: fake-super-secret-token header. Missing header -> 422; present-but-wrong -> 400.

Common situations: Header-token authentication where the client forgets or misnames the header, or where the secret was rotated on the server only.

Related errors

• X-Key header invalid
• X-Key header invalid
• X-Token header invalid
• Inactive user
• Inactive user

AI-assisted analysis of tiangolo/fastapi@3e8d1526d8 (2026-08-11). Data as JSON: /api/errors/41e3e679b05f6bf3. Report an issue: GitHub.

Appendix: 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 3e8d1526d8)