{"record":{"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/3e8d1526d83a90aaf7d6eb6dc682bf150f180b25/docs_src/handling_errors/tutorial002_py310.py#L1-L17","documentation":"HTTPException(404) variant that adds custom response headers. Same trigger as the basic not-found case, but the response includes an X-Error header. Demonstrates that HTTPException accepts a `headers` dict that FastAPI merges into the error response.","triggerScenarios":"GET /items-header/{item_id} where item_id != 'foo'. Response carries header X-Error: 'There goes my error'.","commonSituations":"Returning machine-readable error metadata in headers (correlation ids, error codes) without polluting the body. Developers hit the 404 the same way as the plain variant.","solutions":["Request GET /items-header/foo to succeed.","If you rely on the X-Error header client-side, parse response headers, not just the body.","Use the headers pattern to attach request/correlation ids for tracing."],"exampleFix":"// before\nraise HTTPException(status_code=404, detail=\"Item not found\", headers={\"X-Error\": \"There goes my error\"})\n// after (correlation id)\nraise HTTPException(status_code=404, detail=\"Item not found\", headers={\"X-Request-Id\": request_id})","handlingStrategy":"validation","validationCode":"items = {'foo': 'The Foo Wrestlers'}\nassert item_id in items","typeGuard":"def item_exists(item_id: str, items: dict) -> bool:\n    return item_id in items","tryCatchPattern":"resp = requests.get(f'http://localhost:8000/items-header/{item_id}')\nif resp.status_code == 404:\n    print('404, X-Error header:', resp.headers.get('X-Error'))","preventionTips":["Parse response headers when you expect X-Error metadata.","Use headers for correlation ids rather than body pollution.","Validate ids client-side before sending."],"tags":["fastapi","http-404","headers","httpexception"],"backgroundTag":null,"analyzedSha":"3e8d1526d83a90aaf7d6eb6dc682bf150f180b25","analyzedAt":"2026-08-11T02:34:52.986Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}