docs and some error handling