"""One error shape for the whole API: {"error": {"code", "message", "hint"}}.""" from __future__ import annotations from starlette.exceptions import HTTPException from starlette.responses import JSONResponse class ApiError(HTTPException): """A refusal the client can act on. ``message`` is one plain sentence, ``hint`` says what to do.""" def __init__(self, status: int, code: str, message: str, hint: str, headers: dict[str, str] | None = None): super().__init__(status_code=status, detail=message, headers=headers) self.code = code self.message = message self.hint = hint def error_body(code: str, message: str, hint: str) -> dict: return {"error": {"code": code, "message": message, "hint": hint}} def error_response(status: int, code: str, message: str, hint: str, headers: dict[str, str] | None = None) -> JSONResponse: return JSONResponse(error_body(code, message, hint), status_code=status, headers=headers)