add note about error conditions
slightly rectify docs