It is important to understand the difference between two general types of matchers, branch matchers and leaf matchers. Leaf matchers match things like attributes and strings, while branch matchers are more concerned with structure, such as tag matchers. In general, leaf matchers should never call the xml-validation-error function, and branch matchers should be very careful about calling it. There are no hard and fast rules, unfortunately.
When in doubt, don't call xml-validation-error. Chances are, things will be just fine if you don't.