The javax.lang.model APIs are used in situations where the program constructs being modeled are ill-formed in some way.

Besides the detailed guidance in the package documentation for javax.lang.model.elements on handling erroneous cases in annotation processing, a more encompassing statement in javax.lang.model would be helpful too. For example, a statement that an error object of some form should be returned rather than an exception being thrown.