"""Canonical error envelope: {"error": {"code", "message", "request_id"}}.""" class ApiError(Exception): def __init__(self, status: int, code: str, message: str): self.status = status self.code = code self.message = message super().__init__(message) def bad_request(message: str) -> ApiError: return ApiError(400, "invalid_request", message) def unauthorized(message: str = "authentication required") -> ApiError: return ApiError(401, "unauthorized", message) def not_found(message: str = "not found") -> ApiError: return ApiError(404, "not_found", message) def conflict(message: str) -> ApiError: return ApiError(409, "conflict", message) def unavailable(message: str = "dependency unavailable") -> ApiError: return ApiError(503, "unavailable", message) def payload_too_large(message: str) -> ApiError: return ApiError(413, "payload_too_large", message) def unsupported_media_type(message: str) -> ApiError: return ApiError(415, "unsupported_media_type", message)