Lemme cite an example before explaining the cause.
- Updated the amount of an contribution id n via Contribution.create api from $100 to $150 and "Execute"d it from API Explorer. (No validation error)
- Open the edit back-office contribution form of same contribution ID n. The amount is rightfully changed to $150, but problem is when without doing anything simply save the form and it throws a validation error "Net amount and/or Fee amount must be equal to the Total amount"
The question arises "why didn't I got any validation error at step 1?". Answer lies on the native validation rules written under formRules() func which are not meant for corresponding API.actions. Likewise there are other entity attributes which raise the same concern.
So my suggestion/fix would be to introduce a BAO function for such validation(s),
Flexible enough to accept input params from both APIs and Forms
Provide API Exception(s) and validation error(s) for APIs and Forms respectively
Optimize API and Form validations
And of course would be a BAO function to get called in both APIs and Forms