tiangolo/fastapi · warning · UnicornException

Oops! did something. There goes a rainbow...

Error message

Oops! {exc.name} did something. There goes a rainbow...

What it means

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.

Solutions

1. Avoid requesting /unicorns/yolo if you want a 200.
2. Register an exception_handler for your domain exceptions to control status code and body shape.
3. If 418 is undesirable, change the handler's status_code to a more accurate value (e.g. 400).

Example fix

// before
@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request, exc):
    return JSONResponse(status_code=418, content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."})
// after
return JSONResponse(status_code=400, content={"message": f"Invalid unicorn name: {exc.name}"})

if name == 'yolo':
    print('will trigger 418 UnicornException')

def is_safe_unicorn_name(name: str) -> bool:
    return name != 'yolo'

resp = requests.get(f'http://localhost:8000/unicorns/{name}')
if resp.status_code == 418:
    print('UnicornException:', resp.json()['message'])

When it happens

Trigger: GET /unicorns/yolo. Any other name (e.g. GET /unicorns/sparkles) returns 200 with {unicorn_name: name}. Only 'yolo' triggers the 418.

Common situations: Mapping domain-specific exceptions to HTTP responses without raising HTTPException in business logic. Developers see 418 when their input matches a 'bad' sentinel value.

Related errors

• Nope! I don't like 3.
• Nope! I don't like 3.
• Owner error
• A frontend path cannot be empty
• A frontend path must start with '/'

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

Appendix: source

Thrown at docs_src/handling_errors/tutorial003_py310.py:24

    def __init__(self, name: str):
        self.name = name


app = FastAPI()


@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."},
    )


@app.get("/unicorns/{name}")
async def read_unicorn(name: str):
    if name == "yolo":
        raise UnicornException(name=name)
    return {"unicorn_name": name}

View on GitHub (pinned to 3e8d1526d8)