beginning to lock down the API, improving error messages