more consistent error if ott id is missing, and documentation improvements