API: better error handling and documentation