Document returned errors, and tighten up some related error handling