more api documentation better error signaling and logging