use documented api
a better error message when code is invalid