Exceptions & Error Handling API

`HTTPException`

Raise to return an HTTP error response:

from justapi import HTTPException

raise HTTPException(
    status_code=404,
    detail="Item not found",
    headers={"X-Error": "not_found"},
)

Parameter	Type	Default	Description
`status_code`	`int`	required	HTTP status code
`detail`	`str`	`""`	Error message
`headers`	`dict`	`None`	Additional response headers

`RequestValidationError`

Raised automatically when Pydantic validation fails:

from justapi import RequestValidationError

@app.exception_handler(RequestValidationError)
def handler(request, exc: RequestValidationError):
    return {
        "status": 422,
        "body": {"error": "Validation Failed", "issues": exc.errors()},
    }

Attribute	Type	Description
`.errors()`	`list`	List of validation error details

Exception Handlers

Register custom handlers with @app.exception_handler():

@app.exception_handler(HTTPException)
def custom_handler(request, exc: HTTPException):
    return {
        "status": exc.status_code,
        "body": {"error": exc.detail, "code": exc.status_code},
    }

Precedence

Exception handlers are matched in order:

Exact exception class handler
Parent class handler
Exception catch-all handler

Default Error Codes

Status	Error	When
400	Bad Request	Malformed request
401	Unauthorized	Missing/invalid auth
403	Forbidden	Insufficient permissions
404	Not Found	Unmatched route
413	Payload Too Large	Body exceeds `max_body_size`
422	Unprocessable Entity	Validation failure
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unhandled exception
503	Service Unavailable	Pool saturation
504	Gateway Timeout	Request timeout

Error Response Format

Default error body:

{"detail": "<error message>"}

Custom handlers can return any format.

See Also

Error Handling Tutorial — Usage guide
Resilience Patterns — Circuit breakers, rate limiting
Production Checklist — Error handling in production