updated docblock and error message when invalid json returned