{"record":{"id":"19d3c53225d4536f","repo":"tiangolo/fastapi","slug":"oops-exc-name-did-something-there-goes-a-rainb","errorCode":null,"errorMessage":"Oops! {exc.name} did something. There goes a rainbow...","messagePattern":"Oops! (.+?) did something\\. There goes a rainbow\\.\\.\\.","errorType":"http","errorClass":"UnicornException","httpStatus":418,"severity":"warning","filePath":"docs_src/handling_errors/tutorial003_py310.py","lineNumber":24,"sourceCode":"    def __init__(self, name: str):\n        self.name = name\n\n\napp = FastAPI()\n\n\n@app.exception_handler(UnicornException)\nasync def unicorn_exception_handler(request: Request, exc: UnicornException):\n    return JSONResponse(\n        status_code=418,\n        content={\"message\": f\"Oops! {exc.name} did something. There goes a rainbow...\"},\n    )\n\n\n@app.get(\"/unicorns/{name}\")\nasync def read_unicorn(name: str):\n    if name == \"yolo\":\n        raise UnicornException(name=name)\n    return {\"unicorn_name\": name}\n","sourceCodeStart":6,"sourceCodeEnd":26,"githubUrl":"https://github.com/tiangolo/fastapi/blob/3e8d1526d83a90aaf7d6eb6dc682bf150f180b25/docs_src/handling_errors/tutorial003_py310.py#L6-L26","documentation":"This message is produced by a custom exception handler registered for UnicornException, not by an HTTPException. The path operation raises UnicornException(name) when name == 'yolo'; the handler @app.exception_handler(UnicornException) catches it and returns a JSONResponse with status 418 and this message. It demonstrates defining your own exception class and mapping it to a custom response.","triggerScenarios":"GET /unicorns/yolo. Any other name (e.g. GET /unicorns/sparkles) returns 200 with {unicorn_name: name}. Only 'yolo' triggers the 418.","commonSituations":"Mapping domain-specific exceptions to HTTP responses without raising HTTPException in business logic. Developers see 418 when their input matches a 'bad' sentinel value.","solutions":["Avoid requesting /unicorns/yolo if you want a 200.","Register an exception_handler for your domain exceptions to control status code and body shape.","If 418 is undesirable, change the handler's status_code to a more accurate value (e.g. 400)."],"exampleFix":"// before\n@app.exception_handler(UnicornException)\nasync def unicorn_exception_handler(request, exc):\n    return JSONResponse(status_code=418, content={\"message\": f\"Oops! {exc.name} did something. There goes a rainbow...\"})\n// after\nreturn JSONResponse(status_code=400, content={\"message\": f\"Invalid unicorn name: {exc.name}\"})","handlingStrategy":"validation","validationCode":"if name == 'yolo':\n    print('will trigger 418 UnicornException')","typeGuard":"def is_safe_unicorn_name(name: str) -> bool:\n    return name != 'yolo'","tryCatchPattern":"resp = requests.get(f'http://localhost:8000/unicorns/{name}')\nif resp.status_code == 418:\n    print('UnicornException:', resp.json()['message'])","preventionTips":["Avoid sentinel names that trigger custom exceptions.","Register handlers for every domain exception you raise.","Use accurate status codes (418 is playful; 400 is stricter)."],"tags":["fastapi","exception-handler","custom-exception","http-418"],"backgroundTag":null,"analyzedSha":"3e8d1526d83a90aaf7d6eb6dc682bf150f180b25","analyzedAt":"2026-08-11T02:34:52.986Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}