added documentation about failure reasons