{"id":"eaed84acd326fa03","repo":"tiangolo/fastapi","slug":"item-not-found-eaed84","errorCode":null,"errorMessage":"Item not found","messagePattern":"Item not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"docs_src/handling_errors/tutorial002_py310.py","lineNumber":11,"sourceCode":"from fastapi import FastAPI, HTTPException\n\napp = FastAPI()\n\nitems = {\"foo\": \"The Foo Wrestlers\"}\n\n\n@app.get(\"/items-header/{item_id}\")\nasync def read_item_header(item_id: str):\n    if item_id not in items:\n        raise HTTPException(\n            status_code=404,\n            detail=\"Item not found\",\n            headers={\"X-Error\": \"There goes my error\"},\n        )\n    return {\"item\": items[item_id]}\n","sourceCodeStart":1,"sourceCodeEnd":17,"githubUrl":"https://github.com/tiangolo/fastapi/blob/42a41db11f6882807ac3c057b942178d53b97438/docs_src/handling_errors/tutorial002_py310.py#L1-L17","documentation":"Same HTTP 404 \"Item not found\" as error 34 but with an additional custom response header `X-Error: There goes my error` attached via HTTPException(headers=...). FastAPI's default handler forwards those headers onto the response, letting clients/middleware read error metadata out-of-band. The 404 fires when item_id is not in `items`.","triggerScenarios":"GET /items-header/<anything-except-foo>; the response carries status 404, body {\"detail\":\"Item not found\"}, and header X-Error.","commonSituations":"Clients that rely on the X-Error header for branching; CORS/proxies that strip custom headers; forgetting to include headers when raising from other paths.","solutions":["Request /items-header/foo to avoid the 404.","If you maintain the API, keep the header contract stable and document it.","Whitelist X-Error in CORS exposed headers so browsers can read it.","Test that the header is present on the 404 response."],"exampleFix":"# before\nraise HTTPException(\n    status_code=404,\n    detail=\"Item not found\",\n    headers={\"X-Error\": \"There goes my error\"},\n)\n\n# after (centralized helper)\ndef not_found(extra_headers=None):\n    raise HTTPException(status_code=404, detail=\"Item not found\", headers=extra_headers or {})\nnot_found({\"X-Error\": \"missing\"})","handlingStrategy":"try-catch","validationCode":"if item_id not in {\"foo\"}:\n    # skip the call; expected 404 carries X-Error header\n    raise KeyError(item_id)","typeGuard":"def is_known(item_id: str) -> bool:\n    return item_id in {\"foo\"}","tryCatchPattern":"r = client.get(f\"/items-header/{item_id}\")\nif r.status_code == 404:\n    xerr = r.headers.get(\"X-Error\")\n    # branch on X-Error value if present\n    ...","preventionTips":["Expose X-Error in CORS allowed headers if clients are browsers.","Keep the header contract stable across versions.","Test that the header is actually emitted on 404."],"tags":["fastapi","http-404","custom-headers","handling-errors"],"analyzedSha":"42a41db11f6882807ac3c057b942178d53b97438","analyzedAt":"2026-08-04T19:23:32.007Z","schemaVersion":2}