The current API architecture began with this calling convention for checking errors:

$result = civicrm_api(...);
if ($result['is_error']) ...

It quickly became a common problem that callers forgot to check the result for success/failure, so a thin wrapper was introduced which generated an exception instead of returning an error-value:

try {
  $result = civicrm_api3(...);
}
catch (API_Exception $e) {...}

This generally surfaces errors better, but then the next step is: what caused the error? How do I get a backtrace?

The backtrace always points to the wrapper function. If you want the real backtrace, you need to switch back to civicrm_api(), set debug=1, and inspect the output for trace info.

I don't have a quick solution. Questions to elicit thoughts/planning:

• Can one generate a synthetic exception?
• If the initial problem is reported as an exception, and if the error is reported to the consumer as an exception, is there some way to pass that along?
• What are the implications for an existing consumer which uses civicrm_api3() and looks for API_Exception?
• What are the implications for an existing consumer which uses civicrm_api() and looks for a trace?
• How does this fit into the lifecycle of API kernel (e.g. of events/listeners using civi.api.exception)?